DSC 配置文件功能參考

概要

配置文件中可用於運行時處理的函數。

說明

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（） - 將帶有小數部分的字串或數字轉換為整數。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-07-10