DSC 配置文档功能参考

概要

配置文档中可用于运行时处理的函数。

DESCRIPTION

DSC 配置文档支持使用 DSC 在运行时处理的函数来确定文档的值。 这些函数使您能够定义可重用值且更易于维护的配置。

要使 DSC 识别函数，必须将其放在字符串的方括号内。 DSC 配置文档函数使用以下语法：

[<function-name>(<function-parameters>...)]

在 YAML 中使用函数时，必须使用用双引号括起来的字符串值或使用 折叠 或 文本 块语法来指定函数。 当使用 folded 或 literal 块语法时，请始终使用 block chomping 指示符 （）- 来修剪尾随换行符和空行。

# Double quoted syntax
<keyword>: "[<function-name>(<function-parameters>...)]"
# Folded block syntax
<keyword>: >-
  [<function-name>(<function-parameters>...)]
# Literal block syntax
<keyword>: |-
  [<function-name>(<function-parameters>...)]

您可以嵌套函数，将嵌套函数的输出用作外部函数的参数值。 DSC 处理从最内层函数到最外层函数的嵌套函数。

[<outer-function-name>(<nested-function-name>(<nested-function-parameters>))]

读取长函数可能很困难，尤其是当它们深度嵌套时。 您可以使用换行符将长函数分解为更具可读性的格式，并使用折叠或文字块语法。

# Multi-line folded block syntax
<keyword>: >-
  [<outer-function-name>(
    <nested-function-name>(
      <deeply-nested-function-name>(<deeply-nested-function-parameters>)
    )
  )]
# Multi-line literal block syntax
<keyword>: |-
  [<outer-function-name>(
    <nested-function-name>(
      <deeply-nested-function-name>(<deeply-nested-function-parameters>)
    )
  )]

当函数的输出是数组或对象时，您可以访问对象的属性或数组中的项。

要访问输出对象的属性，请在函数的右括号后面加上句点 （.），然后是要访问的属性的名称。 您还可以访问嵌套对象和数组的属性。

# Accessing a top-level property syntax
<keyword>: "[<function-name>(<function-parameters>...).<property-name>]"
# Accessing a property nested in another object syntax
<keyword>: "[<function-name>(<function-parameters>...).<property-name>.<nested-property-name>]"
# Accessing a property nested in an array item syntax
<keyword>: "[<function-name>(<function-parameters>...)[<index>].<nested-property-name>]"

要访问数组输出中的特定项目，请在函数的右括号后面加上左方括号 （），[然后是要访问的项目的整数索引，然后是右方括号 （]）。 您还可以访问嵌套数组中的项。

# Accessing a top-level array item syntax
<keyword>: "[<function-name>(<function-parameters>...)[<index>]]"
# Accessing an array item nested in a property syntax
<keyword>: "[<function-name>(<function-parameters>...).<property-name>[<nested-array-index>]]"
# Accessing an array item nested in another array syntax
<keyword>: "[<function-name>(<function-parameters>...)[<index>][nested-array-index]]"

例子

示例 1 - 使用具有有效语法的函数

以下配置文档显示了在配置文档中指定函数的三种有效语法。 在每个资源实例中，该 text 属性设置为 base64（） 函数的输出。

# overview.example.1.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Double quoted syntax
    type: Microsoft.DSC.Debug/Echo
    properties:
      text: "[base64('ab')]"
  - name: Folded block syntax
    type: Microsoft.DSC.Debug/Echo
    properties:
      text: >-
        [base64('ab')]
  - name: Literal block syntax
    type: Microsoft.DSC.Debug/Echo
    properties:
      text: |-
        [base64('ab')]

dsc config get --file overview.example.1.dsc.config.yaml

results:
- name: Double quoted syntax
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      text: YWI=
- name: Folded block syntax
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      text: YWI=
- name: Literal block syntax
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      text: YWI=
messages: []
hadErrors: false

示例 2 - 连接两个字符串

以下配置文档将 text 资源实例的属性设置为 concat（） 函数的输出，将字符串 a 和 b 合并到 中 ab。

# overview.example.2.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Echo the concatenated strings 'a' and 'b'
    type: Microsoft.DSC.Debug/Echo
    properties:
      text: "[concat('a', 'b')]"

dsc config get --file overview.example.2.dsc.config.yaml

results:
- name: Echo the concatenated strings 'a' and 'b'
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      text: ab
messages: []
hadErrors: false

示例 3 - 使用嵌套函数

以下配置文档显示了如何嵌套函数。 前两个资源实例使用 concat（） 函数的输出作为 base64（） 函数的输入。 第三个资源实例使用前两个实例的嵌套函数的输出作为函数的 concat() 输入。 最后一个资源实例将第三个实例中显示的深度嵌套函数的输出转换为 base64。

# overview.example.3.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Echo the concatenated strings 'a' and 'b' as base64
    type: Microsoft.DSC.Debug/Echo
    properties:
      text: "[base64(concat('a', 'b'))]"
  - name: Echo the concatenated strings 'c' and 'd' as base64
    type: Microsoft.DSC.Debug/Echo
    properties:
      text: "[base64(concat('c', 'd'))]"
  - name: Echo the concatenated base64 of strings 'ab' and 'cd'
    type: Microsoft.DSC.Debug/Echo
    properties:
      text: "[concat(base64(concat('a', 'b')), base64(concat('c', 'd')))]"
  - name: Echo the concatenated base64 of strings 'ab' and 'cd' as base64
    type: Microsoft.DSC.Debug/Echo
    properties:
      # text: "[base64(concat(base64(concat('a', 'b')), base64(concat('c', 'd'))))]"
      text: >-
        [base64(
          concat(
            base64(concat('a', 'b')),
            base64(concat('c', 'd'))
          )
        )]

dsc config get --file overview.example.3.dsc.config.yaml

results:
- name: Echo the concatenated strings 'a' and 'b' as base64
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      text: YWI=
- name: Echo the concatenated strings 'c' and 'd' as base64
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      text: Y2Q=
- name: Echo the concatenated base64 of strings 'ab' and 'cd'
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      text: YWI=Y2Q=
- name: Echo the concatenated base64 of strings 'ab' and 'cd' as base64
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      text: WVdJPVkyUT0=
messages: []
hadErrors: false

示例 4 - 访问对象属性和数组项

以下配置文档显示了如何访问数组中对象和项的属性。 该示例使用共享参数定义文件，以便更轻松地在每个配置文档中引用单个数据源。

parameters 文件定义了两个参数：

• 参数 data 是一个复杂对象。 该 message 属性是一个嵌套对象。 该 services 属性是一个嵌套数组。
• 参数 list 是一个复杂数组。 数组中的第三项是对象。 数组中的第四项是嵌套数组。

# overview.example.4.dsc.parameters.yaml
parameters:
  # Object parameter
  data:
    # Object property as string
    name:  Example 4
    # Object property as integer
    count: 1
    # Object property as nested object
    message:
      text:  Default message
      level: info
      context:
        location: DC01
    # Object property as array
    services:
      - web
      - database
      - application
  # Array parameter
  list:
    # Array item as string
    - first
    # Array item as integer
    - 2
    # array item as object
    - name:  third
      value: 3
    # Array item as nested array
    -
      - Nested first
      - Nested second
      - name: Nested third

第一个配置文档定义了资源的一个实例 Microsoft.DSC.Debug/Echo ，用于显示如何在配置文档中访问对象的属性。

# overview.example.4.properties.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
# Minimal definition of the parameters
parameters:
  data: { type: object }
  list: { type: array }

resources:
  - name: Access the properties of an object
    type: Microsoft.DSC.Debug/Echo
    properties:
      output:
        # Accessing output object
        data: "[parameters('data')]"
        # Accessing properties
        data.name:     "[parameters('data').name]"     # string
        data.count:    "[parameters('data').count]"    # integer
        data.message:  "[parameters('data').message]"  # nested object
        data.services: "[parameters('data').services]" # array

$params=overview.example.4.dsc.parameters.yaml
$config=overview.example.4.properties.dsc.config.yaml
dsc config --parameters-file $params get --file $config

results:
- metadata:
    Microsoft.DSC:
      duration: PT0.133791S
  name: Access the properties of an object
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      output:
        data:
          count: 1
          name: Example 4
          message:
            text: Default message
            level: info
            context:
              location: DC01
          services:
          - web
          - database
          - application
        data.name: Example 4
        data.count: 1
        data.message:
          text: Default message
          level: info
          context:
            location: DC01
        data.services:
        - web
        - database
        - application

下一个配置文档将介绍如何访问嵌套对象属性。

# overview.example.4.nested.properties.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
# Minimal definition of the parameters
parameters:
  data: { type: object }
  list: { type: array }

resources:
  - name: Access the properties of a nested object
    type: Microsoft.DSC.Debug/Echo
    properties:
      output:
        data.message.text:             "[parameters('data').message.text]"
        data.message.level:            "[parameters('data').message.level]"
        data.message.context:          "[parameters('data').message.context]"
        data.message.context.location: "[parameters('data').message.context.location]"

$params=overview.example.4.dsc.parameters.yaml
$config=overview.example.4.nested.properties.dsc.config.yaml
dsc config --parameters-file $params get --file $config

results:
- metadata:
    Microsoft.DSC:
      duration: PT0.0760186S
  name: Access the properties of an object
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      output:
        data.message.text: Default message
        data.message.level: info
        data.message.context:
          location: DC01
        data.message.context.location: DC01

以下配置文档显示了如何访问数组中的项目。

# overview.example.4.items.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
# Minimal definition of the parameters
parameters:
  data: { type: object }
  list: { type: array }

resources:
  - name: Access items in an array
    type: Microsoft.DSC.Debug/Echo
    properties:
      output:
        # Accessing output array
        list: "[parameters('list')]"
        # Accessing array items
        list[0]: "[parameters('list')[0]]" # string
        list[1]: "[parameters('list')[1]]" # integer
        list[2]: "[parameters('list')[2]]" # object
        list[3]: "[parameters('list')[3]]" # nested array

$params=overview.example.4.dsc.parameters.yaml
$config=overview.example.4.items.dsc.config.yaml
dsc config --parameters-file $params get --path $config

results:
- metadata:
    Microsoft.DSC:
      duration: PT0.0750682S
  name: Access items in an array
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      output:
        list:
        - first
        - 2
        - name: third
          value: 3
        - - Nested first
          - Nested second
          - name: Nested third
        list[0]: first
        list[1]: 2
        list[2]:
          name: third
          value: 3
        list[3]:
        - Nested first
        - Nested second
        - name: Nested third

以下配置文档显示了如何访问嵌套数组中的项目。

# overview.example.4.nested.items.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
# Minimal definition of the parameters
parameters:
  data: { type: object }
  list: { type: array }

resources:
  - name: Access items in a nested array
    type: Microsoft.DSC.Debug/Echo
    properties:
      output:
        list[3][0]: "[parameters('list')[3][0]]"
        list[3][1]: "[parameters('list')[3][1]]"
        list[3][2]: "[parameters('list')[3][2]]"

$params=overview.example.4.dsc.parameters.yaml
$config=overview.example.4.nested.items.dsc.config.yaml
dsc config --parameters-file $params get --file $config

results:
- metadata:
    Microsoft.DSC:
      duration: PT0.1349442S
  name: Access items in a nested array
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      output:
        list[3][0]: Nested first
        list[3][1]: Nested second
        list[3][2]:
          name: Nested third

最后一个配置文档展示了如何同时使用 property 和 item 访问语法来访问复杂对象中的值。

# overview.example.4.mixed.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
# Minimal definition of the parameters
parameters:
  data: { type: object }
  list: { type: array }

resources:
  - name: Access values in complex objects and arrays
    type: Microsoft.DSC.Debug/Echo
    properties:
      output:
        # Accessing array items of an object property
        data.services[0]: "[parameters('data').services[0]]"
        data.services[1]: "[parameters('data').services[1]]"
        data.services[2]: "[parameters('data').services[2]]"
        # Accessing properties of an object in an array
        list[2].name:  "[parameters('list')[2].name]"
        list[2].value: "[parameters('list')[2].value]"
        # Accessing the property of an object in a nested array
        list[3][2].name: "[parameters('list')[3][2].name]"

$params=overview.example.4.dsc.parameters.yaml
$config=overview.example.4.mixed.dsc.config.yaml
dsc config --parameters-file $params get --file $config

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
# Minimal definition of the parameters
parameters:
  data: { type: object }
  list: { type: array }

resources:
  - name: Access values in complex objects and arrays
    type: Microsoft.DSC.Debug/Echo
    properties:
      output:
        # Accessing array items of an object property
        data.services[0]: "[parameters('data').services[0]]"
        data.services[1]: "[parameters('data').services[1]]"
        data.services[2]: "[parameters('data').services[2]]"
        # Accessing properties of an object in an array
        list[2].name:  "[parameters('list')[2].name]"
        list[2].value: "[parameters('list')[2].value]"
        # Accessing the property of an object in a nested array
        list[3][2].name: "[parameters('list')[3][2].name]"

Functions

以下部分包括按用途和输入类型划分的可用 DSC 配置函数。

数组函数

以下函数列表对数组进行作：

• concat（） - 将多个字符串数组合并为一个字符串数组。
• createArray（） - 从零个或多个相同类型的值创建给定类型的数组。
• min（） - 返回整数数组中的最小整数值。
• max（） - 返回整数数组中的最大整数值。

数据函数

以下函数列表对资源实例外部的数据进行作：

• envvar（） - 返回指定环境变量的值。
• parameters（） - 返回指定配置参数的值。
• variables（） - 返回指定配置变量的值。

数学函数

以下函数列表对整数值或整数值数组进行作：

• add（） - 返回两个整数之和。
• div（） - 将两个整数的被除数作为整数返回，并删除结果的其余部分（如果有）。
• int（） - 将带有小数部分的字符串或数字转换为整数。
• max（） - 返回整数数组中的最大值。
• min（） - 返回整数数组中的最小值。
• mod（） - 返回两个整数除法的余数。
• mul（） - 返回两个整数相乘的乘积。
• sub（） - 返回从一个整数中减去另一个整数的差值。

资源功能

以下函数列表对资源实例进行作：

• reference（） - 返回另一个资源实例的结果数据。
• resourceId（） - 返回要引用或依赖的另一个资源实例的 ID。

字符串函数

以下函数列表用于作字符串：

• base64（） - 返回字符串的 base64 表示形式。
• concat（） - 返回一个组合字符串，其中输入字符串按指定的顺序连接。

类型函数

以下函数列表创建或转换给定类型的值：

• createArray（） - 从零个或多个相同类型的值创建给定类型的数组。
• int（） - 将带有小数部分的字符串或数字转换为整数。