DSC 配置文档函数参考

2024-05-11

摘要

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

说明

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

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

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

在 YAML 中使用函数时，必须使用用双引号包装的字符串值指定函数，或者使用折叠或文本块语法。使用折叠或文本块语法时，请始终使用块分隔指示器 (-) 来剪裁尾部换行符和空行。

# 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>)
    )
  )]

示例

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

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

# overview.example.1.dsc.config.yaml
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
resources:
  - name: Double quoted syntax
    type: Test/Echo
    properties:
      text: "[base64('ab')]"
  - name: Folded block syntax
    type: Test/Echo
    properties:
      text: >-
        [base64('ab')]
  - name: Literal block syntax
    type: Test/Echo
    properties:
      text: |-
        [base64('ab')]

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

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

示例 2 - 连接两个字符串

以下配置文档将资源实例的属性设置为 textconcat () 函数的输出，并将字符串 a 和 b 组合成 ab。

# overview.example.2.dsc.config.yaml
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
resources:
  - name: Echo the concatenated strings 'a' and 'b'
    type: Test/Echo
    properties:
      text: "[concat('a', 'b')]"

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

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

示例 3 - 使用嵌套函数

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

# overview.example.3.dsc.config.yaml
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
resources:
  - name: Echo the concatenated strings 'a' and 'b' as base64
    type: Test/Echo
    properties:
      text: "[base64(concat('a', 'b'))]"
  - name: Echo the concatenated strings 'c' and 'd' as base64
    type: Test/Echo
    properties:
      text: "[base64(concat('c', 'd'))]"
  - name: Echo the concatenated base64 of strings 'ab' and 'cd'
    type: Test/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: Test/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 --input-file overview.example.3.dsc.config.yaml config get

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

函数

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

数组函数

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

concat () - 将多个字符串数组合并为单个字符串数组。
createArray () - 从同一类型的零个或多个值Create给定类型的数组。
min () - 返回整数数组中的最小整数值。
max () - 返回整数数组中的最大整数值。

数据函数

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

envvar () - 返回指定环境变量的值。
parameters () - 返回指定配置参数的值。

数学函数

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

add () - 返回两个整数的总和。
div () - 以整数形式返回两个整数的股息，删除结果的剩余部分（如果有）。
int () - 将包含小数部分的字符串或数字转换为整数。
max () - 返回整数数组中的最大值。
min () - 返回整数数组中的最小值。
mod () - 返回两个整数除法的余数。
mul () - 返回乘以两个整数的乘积。
sub () - 返回从一个整数中减去另一个整数的差值。

Resource functions

以下函数列表在资源实例上运行：

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

字符串函数

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

base64 () - 返回字符串的 base64 表示形式。
concat () - 返回一个组合字符串，其中输入字符串按指定顺序串联。

类型函数

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

createArray () - 从同一类型的零个或多个值Create给定类型的数组。
int () - 将包含小数部分的字符串或数字转换为整数。

通过