INTSourceChangelist:3356804
Availability:Public
Title:BuildGraph 脚本元素
Crumbs:
Description:学习 BuildGraph 的元素。
version:4.13
parent:Programming/Development/BuildGraph
type:Reference
tags:Programming
tags:BuildGraph

[VAR:TopicCompact]
[OBJECT:TopicCompact]
	[PARAM:image]
		![%Programming/Development/BuildGraph/ScriptAnatomy/Elements%](elements_topic.png)
	[/PARAM]
	[PARAM:icon]
		![](%ROOT%/reference_icon.png)(convert:false)
	[/PARAM]
	[PARAM:title]
		%Programming/Development/BuildGraph/ScriptAnatomy/Elements:title%
	[/PARAM]
	[PARAM:description]
		%Programming/Development/BuildGraph/ScriptAnatomy/Elements:description%
	[/PARAM]
	[PARAM:path]
		[RELATIVE:Programming/Development/BuildGraph/ScriptAnatomy/Elements]
	[/PARAM]
[/OBJECT]
[/VAR]

[TOC(start:1 end:2)]

[EXCERPT:BuildGraphScriptElements]

BuildGraph 脚本以 XML 编写。此文档包含 BuildGraph 脚本中的数据类型以及其整体结构。

(#Elements)
## 元素

元素描述它们包含的数据，使它们成为 BuildGraph 脚本的基础构建块之一。下表包含作为元数据提供的项目，将在构建系统上运行时导出。在本地执行任务时它们不会被 BuildGraph 直接使用，将以 `[META]` 标记。

(#GraphStructure)
## 图表结构

一个 BuildGraph 脚本通常由以下元素定义：

* `<Node>`
* `<Aggregate>`
* `<Agent>`
* `<Trigger>`

(#Node)
### 节点

`<Node>` 是 BuildGraph 中执行的最小单位，拥有一套输入和输出。每个 `<Node>` 由按顺序执行的一个任务序列组成。

| 属性 | 类型 | 是否必需？| 描述 |
| ---------------- | ------------ | ------------ | ---------------- |
| Name              | 命名         | 必需     | 节点名。|
| Requires         | 目标列表  | 可选     | 由此节点需要执行的其他节点生成的节点列表、聚合，或标记文件集，由分号间隔。|
| Produces         | 标记列表     | 可选     | 此节点向其他节点提供的标记文件集，由分号间隔。|
| After            | 目标列表  | 可选     | 在此节点之前运行的节点列表，如他们为当前目标的部分（如非当前目标的部分，则无视）。由分号间隔。|
| NotifyOnWarnings | 布尔      | 可选     | 如为 false，此节点将不生成警告通知。只由构建系统使用。默认为 `true`。`[META]` |
| If               | 条件    | 可选     | 将被求值的条件。元素将被无视，除非条件求值为 `true`。|

(#Aggregate)
### 聚合

`<Aggregate>` 声明一个命名聚合，可用作一套其他节点（或生成的标签集）的同义词。

| 属性 | 类型 | 是否必需？| 描述 |                                                                                            |
| ---------------- | ------------ | ------------ | -------------- |
| Name              | 命名         | 必需     | 聚合名。|
| Requires         | 目标列表  | 必需     | 此聚合的依赖性列表。可能是节点、标记的文件集，或代理群组。|
| If               | 条件    | 可选     | 将被求值的条件。元素将被无视，除非条件求值为 `true`。|

(#Agent)
### 代理

`<Agent>` 定义按次序执行的节点上代理的要求（无需清理中间目录）。本地构建时将无视 `<Agent>` 要求，但必须被指定。

| 属性 | 类型 | 是否必需？| 描述 |
| ---------------- | --------------- | ------------ | -----------  |
| Name             | 命名            | 必需     | 群组名。|
| Type             | 辨识符列表 | 可选     | 运行的代理类型。此字符串的含义由 host 构建系统所推断；它不含任何本质含义。`[META]` |
| If               | 条件       | 可选     | 将被求值的条件。元素将被无视，除非条件求值为 `true`。|

(#Trigger)
### 触发

`<Trigger>` 的作用是图表部分（该图表只在显式用户介入后执行）的一个容器。如需在触发后执行节点，将 `-Trigger=<Name>` 传至命令行。 

| 属性 | 类型 | 是否必需？| 描述 |
| ---------------- | --------------- | ------------ | ------------------ |
| Name             | 命名            | 必需     | 触发名。|
| If               | 条件       | 可选     | 将被求值的条件。元素将被无视，除非条件求值为 `true`。|

(#PropertyManipulation)
## 属性操作

BuildGraph 属性可通过以下元素进行修改：

* `<Property>`
* `<Option>`
* `<EnvVar>`

(#Property)
### 属性

`<Property>` 设置属性的数值。如外部作用域中的属性已使用相同命名声明，`<Property>` 会将其覆盖。否则将在当前作用域中声明一个新属性。

| 属性 | 类型 | 是否必需？| 描述 |
| ---------------- | ---------- | -------- | -------------- |
| Name             | 命名       | 必需 | 设置的属性名。|
| Value            | 字符串     | 必需 | 属性的新值。|
| If               | 条件  | 可选 | 将被求值的条件。元素将被无视，除非条件求值为 `true`。|

(#Option)
### 选项

`<Option>` 定义可从命令行进行设置的用户选项。`<Option>` 可能只出现在全局作用域。

| 属性 | 类型 | 是否必需？| 描述 |
| ------------ | --------- | ------------ | ------------- |
| Name         | 命名      | 必需     | 通过选项数值初始化的选项（和属性）名。|
| Description  | 字符串    | 必需     | 通过 -ListOnly 参数运行 BuildGraph 时选项显示的描述。|
| Restrict     | 正则表达式     | 可选     | 匹配此选项有效数值的正则表达式（如 `[a-zA-Z]+`, `true | false`）。|
| DefaultValue | 字符串    | 必需     | 用户不进行显式设置时的选项默认值。|
| If           | 条件 | 可选     | 将被求值的条件。元素将被无视，除非条件求值为 `true`。|

### EnvVar

`<EnvVar>` 声明属性，以包含环境变量的内容（如未设置则为空白字符串）。
`<EnvVar>` 可能只出现在全局作用域。

| 属性 | 类型 | 是否必需？| 描述 |
| ------------ | --------- | ------------ | ------------- |
| Name             | Name        | Required | 作为属性引入的环境变量名。|
| If               | 条件   | 可选 | 将被求值的条件。元素将被无视，除非条件求值为 `true`。|

(#FlowControl)
## 流动控制

可通过以下元素控制 BuildGraph 脚本的流动。

* `<Include>`
* `<Do>`
* `<Switch>`
* `<ForEach>`

(#Include)
### 包括

`<Include>` 处理其他 BuildGraph 脚本的内容，就像它存在出现在此文件中那样。
`<Include>` 可能只出现在全局作用域。

| 属性 | 类型 | 是否必需？| 描述 |
| ------------ | --------- | ------------ | ------------- |
| Script           | 字符串          | 必需     | 需要包含的脚本的路径（相对于当前脚本）。|
| If               | 条件       | 可选     | 将被求值的条件。元素将被无视，除非条件求值为 `true`。|

### Do

`<Do>` 将元素的序列分组，仅在条件求值为 true 时对它们进行处理。

| 属性 | 类型 | 是否必需？| 描述 |
| ------------ | --------- | ------------ | ------------- |
| If | 条件 | 可选 | 将被求值的条件。元素将被无视，除非条件求值为 `true`。|

(#Switch)
### 切换

`<Switch>` 与 [C](http://www.open-std.org/jtc1/sc22/wg14/www/standards) 切换语句相似，因其在分支序列上对条件求值，使用求值为 true 的条件处理首个语句。

`<Switch>` 语句示例：

	<Switch>
		<Case If=X>
			<Elements go here>
		</Case>
		<Case If=Y>
			<Elements go here>
		</Case>
		<Default>
			<Elements go here>
		</Default>
	</Switch>
	
| 属性 | 类型 | 是否必需？| 描述 |
| ------------ | --------- | ------------ | ------------- |
| If | 条件 | 可选 | 将被求值的条件。元素将被无视，除非条件求值为 `true`。|

### ForEach

`<ForEach>` 通过在一个列表中指定到每个项目的给定属性（由分号间隔）来展开元素主体。

`<ForEach>` 语句示例：

	<ForEach Name="Counter" Values="1;2;3;4;5">
		<Log Message="Counter=$(Counter)"/>
	</ForEach>
	
| 属性 | 类型 | 是否必需？| 描述 |
| ------------ | --------- | ------------ | ------------- |
| Name             | 命名            | 必需     | 指定到列表中每个数值的属性。|
| Values           | 字符串列表     | 必需     | 数值列表，由分号间隔。|
| If               | 条件       | 可选     | 将被求值的条件。元素将被无视，除非条件求值为 `true`。|

(#Diagnostics)
## 诊断

可通过以下元素对 BuildGraph 脚本执行诊断。

* `<Warning>`
* `<Error>`

(#Warning)
### 警告

`<Warning> 会在执行图表前输出警告消息。`<Warning>` 可能包含在节点、代理、触发、或整体作用域中。如 `<Warning>` 在被裁剪到被执行的目标后仍为图表的一部分，它将只提供一个输出。

| 属性 | 类型 | 是否必需？| 描述 |
| ------------ | --------- | ------------ | ------------- |
| Message          | 字符串          | 必需     | 被打印到日志的文本。|
| If               | 条件       | 可选     | 将被求值的条件。元素将被无视，除非条件求值为 `true`。|

(#Error)
### 错误

`<Error>` 将输出错误消息。`<Error>` 可能包含在节点、代理、触发、或整体作用域中。如 `<Error>` 在被裁剪到被执行的目标后仍为图表的一部分，它将只提供一个输出。

| 属性 | 类型 | 是否必需？| 描述 |
| ------------ | --------- | ------------ | ------------- |
| Message          | 字符串          | 必需     | 被打印到日志的文本。|
| If               | 条件       | 可选     | 将被求值的条件。元素将被无视，除非条件求值为 `true`。|

[/EXCERPT:BuildGraphScriptElements]

[EXCERPT:BuildGraphScriptTasks]
(#Tasks)
### 任务

通常而言，项目特定的实用脚本被实现为 AutomationTool BuildCommand 类。然而有时您需要为项目自动化自定义任务。这时 BuildGraph 便可提供协助。BuildGraph 可通过任意数量的任务进行延展，便于您用最符合自身需求的方式自定义构建自动化任务。以下部分将说明使用 BuildGraph 创建自定义任务的多种方式，包括预定义任务的列表，为创建自定义任务提供良好的起始点。

(#CustomTasks)
## 自定义任务

如需新建自定义任务，需实现一个派生自 `CustomTask` 类的类并对其应用 `[TaskElement]` 属性。`TaskElement` 构造函数拥有两个参数：其所代表的 XML 元素的命名、和包含其参数的类类型（将在加载时传至构造函数）。

如需从 XML 文件读取参数类域，将 `[TaskParameter]` 属性附加到任务。附加 `TaskParameter` 属性将说明形式参数为必须或可选，包括应被应用到实际参数的额外验证。

(#PredefinedTasks)
## 预定义任务

作为创建任务的起始点，我们提供各种预定义任务供您使用。如果需要上手使用的简单预定义任务，我们推荐将 `LogTask` 用作一个较好的起始点。如需了解 BuildGraph 的最新改良，请将此页设为书签，以下预定义任务列表将定期更新。 

[INCLUDE:Programming/Development/BuildGraph/ScriptAnatomy/Tasks/PredefinedTasks]

[/EXCERPT:BuildGraphScriptTasks]