DSC-Konfigurationsparameter – Datentypschemareferenz

2024-05-09

Übersicht

Definiert gültige Datentypen für einen DSC-Konfigurationsparameter.

Metadaten

SchemaDialect: https://json-schema.org/draft/2020-12/schema
SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/dataTypes.json
Type:          string
ValidValues:   [array, bool, int, object, string, secureobject, securestring]

Beschreibung

Parameter in einem DSC-Konfigurationsdokument müssen ein gültiger Datentyp sein.

Die gültigen Datentypen für einen Parameter sind:

array für Arrays
bool für Boolesche
int für ganze Zahlen
object für Objekte
string für Zeichenfolgen
secureobject für sichere Objekte
securestring für sichere Zeichenfolgen

Greifen Sie auf Parameter in einer Konfiguration mit der folgenden Syntax zu:

"[parameter('<parameter-name>')]"

In YAML muss die Parametersyntax bei Verwendung als Inlinewert in doppelte Anführungszeichen eingeschlossen werden. Wenn die Syntax nicht in Anführungszeichen angegeben ist, interpretiert YAML die Syntax als Array.

valid:  "[parameter('example')]"
# This unquoted syntax:
invalid: [parameter('example')]
# Evaluates to this YAML:
invalid:
  - parameter('example')

Arrays

Arrays sind eine Liste mit mindestens einem Wert. Bei den Werten im Array kann es sich um einen beliebigen gültigen Datentyp handeln. Werte im Array können derselbe Typ oder unterschiedliche Typen sein.

parameters:
  exampleIntArray:
    type: array
    defaultValue:
      - 1
      - 2
      - 3
  exampleMixedArray:
    type: array
    defaultValue:
      - 1
      - true
      - example string

Der Zugriff auf Elemente in einem Array kann anhand ihres Indexes möglich sein. Das erste Element in einem Array ist index 0. Verwenden Sie diese Syntax, um auf einen Index in einem Arrayparameter zuzugreifen:

"[parameter('<parameter-name>')[<index>]]"

parameters:
  members:
    type: array
    defaultValue:
      - first
      - second
      - third
resources:
  # Use the entire array as the value for a resource property
  - name: Operators Group
    type: Example.Security/Group
    properties:
      groupName: operators
      members: "[parameter('members')]"
  # Use a single item in the array as the value for a resource property
  - name: Admin Group
    type: Example.Security/Group
    properties:
      groupName: admins
      members:
        - "[parameter('members')[0]]"

Boolesche Werte

Boolesche Werte sind entweder true oder false.

parameters:
  exampleBool:
    type:         bool
    defaultValue: true

Ganze Zahlen

Ganzzahlige Werte sind Zahlen ohne Bruchteil. Ganzzahlige Werte können durch die Integration von Tools oder die DSC-Ressourcen, mit denen sie verwendet werden, eingeschränkt werden. DSC selbst unterstützt ganzzahlige Werte zwischen -9223372036854775808 und 9223372036854775807.

parameters:
  exampleInt:
    type:         int
    defaultValue: 12

Objekte

Objekte definieren einen Satz von Schlüssel-Wert-Paaren. Der Wert für jeden Schlüssel kann ein beliebiger gültiger Datentyp sein. Die Werte können denselben Typ oder unterschiedliche Typen aufweisen.

parameters:
  exampleObject:
    type: object
    defaultValue:
      scope:               machine
      updateAutomatically: true
      updatefrequency:     30

Zugriffsschlüssel im -Objekt mithilfe der Punktnotation. Die Punktnotation verwendet diese Syntax:

"[parameters('<parameter-name>').<key-name>]

parameters:
  tstoy:
    type: object
    defaultValue:
      scope:               machine
      updateAutomatically: true
      updatefrequency:     30
  registryKeys:
    type: object
    defaultValue:
      productName:
        keyPath:   HKLM\Software\Microsoft\Windows NT\CurrentVersion
        valueName: ProductName
      systemRoot:
        keyPath:   HKLM\Software\Microsoft\Windows NT\CurrentVersion
        valueName: SystemRoot
resources:
  # Use the base object for the property definition
  - name: TSToy
    type: TSToy.Example/gotstoy
    properties: "[parameter('tstoy')]"
  # Use dot-notation for the property definition
  - name: Windows Product Name
    type: Microsoft.Windows/Registry
    properties: "[parameter('registryKeys').productName]"
  # Use dot-notation for each value in the property definition
  - name: Windows System Root
    type: Microsoft.Windows/Registry
    properties:
      keyPath:   "[parameters('registryKeys').systemRoot.keyPath]"
      valueName: "[parameters('registryKeys').systemRoot.valueName]"

Zeichenfolgen

Zeichenfolgen sind ein beliebiger Textsatz.

parameters:
  exampleString:
    type: string
    defaultValue: This example includes spaces and 'quoted' "text."

Um eine lange Zeichenfolge ohne Zeilenumbrüche in YAML zu definieren, verwenden Sie die Syntax des gefalteten Blocks, indem Sie einen > und einen Zeilenumbruch nach dem Schlüssel hinzufügen. Dann die nächste Zeile einziehen. Jede Zeile in der Zeichenfolge muss auf der gleichen Ebene des Einzugs beginnen. Die Linien werden mit einem einzelnen Leerzeichen anstelle von Zeilenneulinien kombiniert. Um nachfolgende Leerzeichen zu kürzen, verwenden Sie >- anstelle von >.

parameters:
  foldedBlockExample:
    type: string
    defaultValue: >-
      This example spans multiple lines
      in the definition, but the lines are
      joined with spaces instead of newlines.

Um eine lange Zeichenfolge mit Zeilenumbrüchen in YAML zu definieren, verwenden Sie die Syntax des Literalblocks, indem Sie einen | und einen Zeilenumbruch nach dem Schlüssel hinzufügen. Dann die nächste Zeile einziehen. Jede Zeile in der Zeichenfolge muss mit der gleichen Oder höher beginnen. Die Linien werden wörtlich interpretiert, aber der führende Einzug wurde entfernt. Wenn Zeilen nach der ersten Zeile mehr als die erste Zeile eingezogen werden, wird nur der zusätzliche Einzug beibehalten. Um nachfolgende Leerzeichen zu kürzen, verwenden Sie |- anstelle von |.

parameters:
  literalBlockExample:
    type: string
    defaultValue: |-
      This example spans multiple lines
      in the definition.

      It can even include paragraphs.

        When a line is indented further
        than the first line, that extra
        indentation is preserved.

Sichere Zeichenfolgen und Objekte

Sichere Zeichenfolgen verwenden das gleiche Format wie Zeichenfolgen, und sichere Objekte verwenden das gleiche Format wie Objekte. Die secure* Datentypen geben an, dass DSC und Integrationstools die Werte nicht protokollieren oder aufzeichnen sollten. Wenn ein sicherer Datentypparameter für eine Ressource instance Eigenschaft verwendet wird, die keinen sicheren Wert erwartet, kann die Ressource den Wert trotzdem protokollieren oder aufzeichnen. Wenn die Ressource über eine unabhängige Protokollierung oder Aufzeichnung verfügt, die nicht von DSC verarbeitet wird, wird der Wert möglicherweise unsicher gespeichert.

Verwenden Sie sichere Zeichenfolgen für Kennwörter und Geheimnisse. Definieren Sie niemals einen Standardwert für Parameter für sichere Zeichenfolgen oder sichere Objekte.

parameters:
  password:
    type: securestring
  sensitiveOptions:
    type: secureobject

Freigeben über