Referens för dokumentfunktioner för DSC-konfiguration

Artikel
05/11/2024

Synopsis

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

Description

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 är enklare att underhålla.

För att DSC ska kunna identifiera en funktion måste den placeras inom hakparenteser i en sträng. Dokumentfunktioner för DSC-konfiguration 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 är omslutet med dubbla citattecken eller använder den vikta eller literala blocksyntaxen. När du använder syntaxerna för vikta eller literalblock ska du alltid använda indikatorn för blockkvävning (-) för att trimma avslutande radbrytningar och tomma linjer.

# 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 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 radbrytningar för att dela upp långa funktioner i ett mer läsbart format med den vikta eller literala blocksyntaxen.

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

Exempel

Exempel 1 – Använd en funktion med giltiga syntaxer

Följande konfigurationsdokument visar de tre giltiga syntaxerna för att ange en funktion i ett konfigurationsdokument. I varje resursinstans text anges egenskapen till utdata för funktionen 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

Exempel 2 – Sammanfoga två strängar

Följande konfigurationsdokument anger text egenskapen för resursinstansen till utdata från funktionen concat(), som kombinerar strängarna a och b till 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

Exempel 3 – Använda kapslade funktioner

Följande konfigurationsdokument visar hur du kan kapsla funktioner. De första två 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 djupt kapslade funktioner som visas i den tredje instansen till 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

Functions

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

Matrisfunktioner

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 fler värden av samma typ.
min() – Returnera det minsta heltalsvärdet från en matris med heltal.
max() – Returnera det största heltalsvärdet från en matris med heltal.

Datafunktioner

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

envvar() – Returnera värdet för en angiven miljövariabel.
parameters() – Returnera värdet för en angiven konfigurationsparameter.

Matematikfunktioner

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

add() – Returnera summan av två heltal.
div() – Returnera utdelningen för två heltal som ett heltal och släpp resten av resultatet, om det finns några.
int() – Konvertera en sträng eller ett tal med en bråkdel till ett heltal.
max() – Returnera det största värdet från en matris med heltal.
min() – Returnera 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 att referera till eller vara beroende av.

Strängfunktioner

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

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

Typfunktioner

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

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

Dela via