Dela via

Funktionsreferens för DSC-konfigurationsdokument

Sammanfattning

Funktioner som är tillgängliga i ett konfigurationsdokument för körningsbearbetning.

Beskrivning

DSC-konfigurationsdokument stöder användning av funktioner som DSC bearbetar vid körning för att fastställa värden för dokumentet. Med de här funktionerna kan du definiera konfigurationer som återanvänder värden och som är enklare att underhålla.

För att DSC ska känna igen en funktion måste den placeras inom hakparenteser i en sträng. Funktioner för DSC-konfigurationsdokument använder följande syntax:

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

När du använder funktioner i YAML måste du ange funktionen med ett strängvärde som omsluts av dubbla citattecken eller använder syntaxen för vikta eller literala block. När du använder syntaxerna för vikta eller literala block ska du alltid använda indikatorn för blockchomping (-) för att trimma avslutande radbrytningar och tomma rader.

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

Du kan kapsla funktioner med hjälp av utdata från en kapslad funktion som ett parametervärde för en yttre funktion. DSC bearbetar kapslade funktioner från den innersta funktionen till den yttersta funktionen.

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

Det kan vara svårt att läsa långa funktioner, särskilt när de är djupt kapslade. Du kan använda nya rader för att dela upp långa funktioner i ett mer läsbart format med syntaxen för vikta eller literala block.

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

När utdata från en funktion är en matris eller ett objekt kan du komma åt egenskaperna för objektet eller objekten i matrisen.

Om du vill komma åt egenskapen för ett utdataobjekt följer du den avslutande parentesen för funktionen med en punkt (.) och sedan namnet på den egenskap du vill komma åt. Du kan också komma åt egenskaperna för kapslade objekt och matriser.

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

Om du vill komma åt ett specifikt objekt i en matrisutdata följer du den avslutande parentesen för funktionen med en inledande hakparentes ([), sedan heltalsindexet för det objekt du vill komma åt och sedan en avslutande hakparentes (]). Du kan också komma åt objekt i kapslade matriser.

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

Exempel

Exempel 1 – Använd en funktion med giltiga syntaxer

I följande konfigurationsdokument visas de tre giltiga syntaxerna för att ange en funktion i ett konfigurationsdokument. I varje resursinstans är egenskapen inställd på text utdata från base64() funktionen.

# 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

Exempel 2 – Sammanfoga två strängar

I följande konfigurationsdokument anges egenskapen för resursinstansen text till utdata från funktionen concat() genom att kombinera strängarna a och b into 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

Exempel 3 – Använda kapslade funktioner

Följande konfigurationsdokument visar hur du kan kapsla funktioner. De två första resursinstanserna använder utdata från funktionen concat() som indata till funktionen base64(). Den tredje resursinstansen använder utdata från de kapslade funktionerna från de två första instanserna som indata till concat() funktionen. Den sista resursinstansen konverterar utdata från de djupt kapslade funktionerna som visas i den tredje instansen till 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

Exempel 4 – Egenskaper för åtkomstobjekt och matrisobjekt

Följande konfigurationsdokument visar hur du kan komma åt egenskaperna för objekt och objekt i matriser. I exemplet används en delad parameterdefinitionsfil för att göra det enklare att referera till en enda datakälla i varje konfigurationsdokument.

Parameterfilen definierar två parametrar:

  • Parametern data är ett komplext objekt. Egenskapen message är ett kapslat objekt. Egenskapen services är en kapslad matris.
  • Parametern list är en komplex matris. Det tredje objektet i matrisen är ett objekt. Det fjärde objektet i matrisen är en kapslad matris.
# 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

Det första konfigurationsdokumentet definierar en instans av resursen Microsoft.DSC.Debug/Echo för att visa hur du kan komma åt ett objekts egenskaper i ett konfigurationsdokument.

# 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

Nästa konfigurationsdokument visar hur du kan komma åt egenskaper för kapslade objekt.

# 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

Följande konfigurationsdokument visar hur du kan komma åt objekt i en matris.

# 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

Följande konfigurationsdokument visar hur du kan komma åt objekt i en kapslad matris.

# 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

Det sista konfigurationsdokumentet visar hur du kan använda syntaxerna för egenskaps- och objektåtkomst tillsammans för att komma åt värden i komplexa objekt.

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

Funktionen

Följande avsnitt innehåller tillgängliga DSC-konfigurationsfunktioner efter syfte och indatatyp.

Array-funktioner

Följande lista över funktioner fungerar på matriser:

  • concat() – Kombinera flera matriser med strängar till en enda matris med strängar.
  • createArray() – Skapa en matris av en viss typ från noll eller flera värden av samma typ.
  • min() – Returnerar det minsta heltalsvärdet från en matris med heltal.
  • max() – Returnera det största heltalsvärdet från en matris med heltal.

Funktioner för data

Följande lista över funktioner fungerar på data utanför en resursinstans:

  • envvar() – Returnerar värdet för en angiven miljövariabel.
  • parameters() – Returnerar värdet för en angiven konfigurationsparameter.
  • variables() – Returnerar värdet för en angiven konfigurationsvariabel.

Matematiska funktioner

Följande lista över funktioner fungerar på heltalsvärden eller matriser med heltalsvärden:

  • add() – Returnerar summan av två heltal.
  • div() – Returnerar utdelningen av två heltal som ett heltal och tar bort resten av resultatet, om det finns något.
  • int() – Konvertera en sträng eller ett tal med en bråkdel till ett heltal.
  • max() – Returnerar det största värdet från en matris med heltal.
  • min() – Returnerar det minsta värdet från en matris med heltal.
  • mod() - Returnera resten från divisionen av två heltal.
  • mul() – Returnera produkten från att multiplicera två heltal.
  • sub() – Returnera skillnaden från att subtrahera ett heltal från ett annat.

Resursfunktioner

Följande lista över funktioner fungerar på resursinstanser:

  • reference() – Returnera resultatdata för en annan resursinstans.
  • resourceId() – Returnera ID:t för en annan resursinstans som ska refereras till eller vara beroende av.

Strängfunktioner

Följande lista med funktioner är till för att manipulera strängar:

  • base64() – Returnera base64-representationen av en sträng.
  • concat() – Returnera en kombinerad sträng där indatasträngarna sammanfogas i den ordning de anges.

Typfunktioner

I följande lista över funktioner skapar eller konverterar du värden av en viss typ:

  • createArray() – Skapa en matris av en viss typ från noll eller flera värden av samma typ.
  • int() – Konvertera en sträng eller ett tal med en bråkdel till ett heltal.
  • Last updated on