Riferimento alle funzioni del documento di configurazione DSC

Riepilogo

Funzioni disponibili all'interno di un documento di configurazione per l'elaborazione runtime.

Descrizione

I documenti di configurazione DSC supportano l'uso di funzioni che DSC elabora in fase di esecuzione per determinare i valori per il documento. Queste funzioni consentono di definire configurazioni che riutilizzano i valori e sono più facili da gestire.

Affinché DSC riconosca una funzione, è necessario che venga inserita tra parentesi quadre in una stringa. Le funzioni del documento di configurazione DSC utilizzano la sintassi seguente:

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

Quando si usano funzioni in YAML, è necessario specificare la funzione con un valore stringa racchiuso tra virgolette doppie o usa la sintassi del blocco piegato o letterale . Quando si utilizzano le sintassi dei blocchi piegati o letterali, utilizzare sempre l'indicatore di masticazione dei blocchi (-) per tagliare le interruzioni di riga finali e le righe vuote.

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

È possibile annidare le funzioni, utilizzando l'output di una funzione nidificata come valore di parametro per una funzione esterna. DSC elabora le funzioni nidificate dalla funzione più interna alla funzione più esterna.

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

Può essere difficile leggere le funzioni lunghe, soprattutto quando sono profondamente annidate. È possibile utilizzare le nuove righe per suddividere le funzioni lunghe in un formato più leggibile con la sintassi a blocchi ripiegati o letterali.

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

Quando l'output di una funzione è una matrice o un oggetto, è possibile accedere alle proprietà dell'oggetto o degli elementi nella matrice.

Per accedere alla proprietà di un oggetto di output, far seguire la parentesi di chiusura della funzione con un punto (.) e quindi il nome della proprietà a cui si desidera accedere. È inoltre possibile accedere alle proprietà degli oggetti nidificati e delle matrici.

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

Per accedere a un elemento specifico nell'output di un array, far seguire la parentesi di chiusura della funzione con una parentesi quadra di apertura ([), quindi l'indice intero dell'elemento a cui si desidera accedere e quindi una parentesi quadra di chiusura (]). È inoltre possibile accedere agli elementi nelle matrici nidificate.

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

Esempi

Esempio 1 - Utilizzare una funzione con sintassi valida

Nel seguente documento di configurazione vengono illustrate le tre sintassi valide per specificare una funzione in un documento di configurazione. In ogni istanza di risorsa, la text proprietà è impostata sull'output della funzione 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

Esempio 2 - Concatenare due stringhe

Il seguente documento di configurazione imposta la text proprietà dell'istanza della risorsa sull'output della funzione concat(), combinando le stringhe a e b in 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

Esempio 3 - Utilizzo di funzioni annidate

Il seguente documento di configurazione mostra come annidare le funzioni. Le prime due istanze di risorse utilizzano l'output della funzione concat() come input per la funzione base64(). La terza istanza della risorsa utilizza l'output delle funzioni annidate delle prime due istanze come input per la concat() funzione. L'ultima istanza della risorsa converte l'output delle funzioni profondamente annidate mostrate nella terza istanza in 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

Esempio 4 - Accedere alle proprietà degli oggetti e agli elementi della matrice

Nei seguenti documenti di configurazione viene illustrato come accedere alle proprietà degli oggetti e degli elementi nelle matrici. Nell'esempio viene utilizzato un file di definizione dei parametri condiviso per semplificare il riferimento a una singola origine dati in ogni documento di configurazione.

Il file dei parametri definisce due parametri:

Il data parametro è un oggetto complesso. La message proprietà è un oggetto nidificato. La services proprietà è una matrice nidificata.
Il list parametro è un array complesso. Il terzo elemento della matrice è un oggetto. Il quarto elemento della matrice è una matrice nidificata.

# 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

Il primo documento di configurazione definisce un'istanza della Microsoft.DSC.Debug/Echo risorsa per mostrare come è possibile accedere alle proprietà di un oggetto in un documento di configurazione.

# 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

Il seguente documento di configurazione mostra come accedere alle proprietà degli oggetti nidificati.

# 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

Il seguente documento di configurazione mostra come accedere agli elementi in un array.

# 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

Il seguente documento di configurazione mostra come accedere agli elementi in un array nidificato.

# 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

L'ultimo documento di configurazione illustra come utilizzare le sintassi di accesso alle proprietà e agli elementi insieme per accedere ai valori in oggetti complessi.

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

Funzioni

Le sezioni seguenti includono le funzioni di configurazione DSC disponibili in base allo scopo e al tipo di input.

Funzioni di array

Il seguente elenco di funzioni opera sugli array:

concat() - Combina più array di stringhe in un singolo array di stringhe.
createArray() - Crea un array di un dato tipo da zero o più valori dello stesso tipo.
min() - Restituisce il valore intero più piccolo da un array di numeri interi.
max() - Restituisce il valore intero più grande da un array di numeri interi.

Funzioni dati

L'elenco seguente di funzioni opera su dati esterni a un'istanza di risorsa:

envvar() - Restituisce il valore di una variabile d'ambiente specificata.
parameters() - Restituisce il valore di un parametro di configurazione specificato.
variables() - Restituisce il valore di una variabile di configurazione specificata.

Funzioni matematiche

L'elenco seguente di funzioni opera su valori interi o matrici di valori interi:

add() - Restituisce la somma di due numeri interi.
div() - Restituisce il dividendo di due numeri interi come numero intero, eliminando il resto del risultato, se presente.
int() - Converte una stringa o un numero con una parte frazionaria in un numero intero.
max() - Restituisce il valore più grande da un array di numeri interi.
min() - Restituisce il valore più piccolo da un array di numeri interi.
mod() - Restituisce il resto dalla divisione di due numeri interi.
mul() - Restituisce il prodotto dalla moltiplicazione di due numeri interi.
sub() - Restituisce la differenza dalla sottrazione di un numero intero da un altro.

Funzioni delle risorse

L'elenco seguente di funzioni opera sulle istanze delle risorse:

reference() - Restituisce i dati dei risultati per un'altra istanza di risorsa.
resourceId() - Restituisce l'ID di un'altra istanza di risorsa a cui fare riferimento o da cui dipendere.

Funzioni di stringa

L'elenco seguente di funzioni serve per la manipolazione delle stringhe:

base64() - Restituisce la rappresentazione base64 di una stringa.
concat() - Restituisce una stringa combinata in cui le stringhe di input sono concatenate nell'ordine in cui sono specificate.

Funzioni per i tipi

Nell'elenco seguente di funzioni viene creato o convertito i valori di un determinato tipo:

createArray() - Crea un array di un dato tipo da zero o più valori dello stesso tipo.
int() - Converte una stringa o un numero con una parte frazionaria in un numero intero.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-07-10