Dela via

DSC-konfigurationsdokument

I Microsofts DSC-plattform (Desired State Configuration) deklarerar DSC-konfigurationsdokument det önskade tillståndet för ett system som datafiler. Konfigurationsdokument definierar en samling DSC-resursinstanser för att beskriva vad det önskade tillståndet ska vara, inte hur systemet ska försättas i det tillståndet. DSC-resurserna hanterar hur för varje instans.

DSC kan bearbeta konfigurationsdokument för att:

  • Hämta det aktuella tillståndet för de definierade resursinstanserna med kommandot dsc config get .
  • Kontrollera om instanserna är i önskat tillstånd med kommandot dsc config test .
  • Framtvinga önskat tillstånd för instanserna med kommandot dsc config set .
  • Exportera ett nytt konfigurationsdokument med varje instans av en uppsättning resurser med kommandot dsc config export .

Konfigurationsdokument är YAML- eller JSON-filer som innehåller ett enda objekt. Objektets egenskaper definierar hur DSC bearbetar dokumentet. Egenskaperna på den översta nivån för ett dokument är:

  • $schema (obligatoriskt) – Definierar URI:n för det JSON-schema som dokumentet följer. DSC använder den här URI:n för att veta hur dokumentet ska valideras och tolkas.

  • resources (obligatoriskt) – Definierar den samling resursinstanser som dokumentet hanterar.

  • metadata (valfritt) – Definierar en godtycklig uppsättning anteckningar för dokumentet. Förutom metadata i Microsoft.DSC egenskapen validerar DSC inte dessa data eller använder dem direkt. Anteckningarna kan innehålla anteckningar som vem som skapade dokumentet, när någon senast uppdaterade det eller annan information. DSC använder inte anteckningarna. Metadata är för dokumentation eller andra verktyg att använda.

    DSC tillämpar validering på egenskapen Microsoft.DSC . Mer information finns i schemareferensen för DSC-konfigurationsdokumentets metadata.

  • parameters (valfritt) – Definierar en uppsättning körningsalternativ för konfigurationen. Resursinstanser kan referera till parametrar för att minska duplicerade definitioner eller aktivera dynamiska värden. Parametrar kan ha standardvärden och kan ställas in för alla konfigurationsåtgärder.

  • variables (valfritt) – Definierar en uppsättning återanvändbara värden för konfigurationen. Resursinstanser kan referera till variabler för att minska dubblettdefinitioner.

Definiera ett konfigurationsdokument

Ett konfigurationsdokument definierar $schema egenskaperna och resources i minsta detalj. Egenskapen $schema måste vara en giltig URI för schemat för DSC-konfigurationsdokumentet. Egenskapen resources måste definiera minst en DSC-resursinstans.

Till exempel:

# example.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: example key value
    type: Microsoft.Windows/Registry
    properties:
      keyPath:   HKCU\example\key
      valueName: Example
      valueData:
        String: This is an example.

Exempeldokumentet definierar en enskild resursinstans med namnet example key value. Instansen använder resursen Microsoft.Windows/Registry för att deklarera följande önskade tillstånd:

  • Registernyckeln example\key ska finnas i systemets aktuella registreringsdatafil.
  • Registernyckeln example\key ska ha ett värde som kallas Example.
  • Värdet Example ska vara strängen This is an example.

Exempeldokumentet är deklarativt. Den beskriver det önskade tillståndet, inte hur systemet ska försättas i det tillståndet. Den förlitar sig på resursen Microsoft.Windows/Registry för att hantera hämtning, testning och inställning av tillståndet för registernyckeln och värdet.

Mer information om strukturen och valideringen av konfigurationsdokument finns i Schemareferens för DSC-konfigurationsdokument.

Definiera resursinstanser

Som du ser i föregående exempel innehåller konfigurationsdokument en samling resursinstanser. Tillsammans beskriver instanserna det önskade tillståndet för ett system. Ett konfigurationsdokument kan innehålla valfritt antal resursinstanser.

En resursinstansdeklaration innehåller alltid:

  • name - Ett kort, läsbart namn för den instans som är unik i dokumentet. Det här namnet används för loggning och hjälper till att beskriva syftet med instansen.
  • type - Det fullständigt kvalificerade typnamnet för den resurs som DSC ska använda för att hantera instansen.
  • properties - Det önskade tillståndet för instansen. DSC verifierar värdena mot resursens instansschema.

Konfigurationsdokument kan inte innehålla samma instans mer än en gång. Att deklarera samma instans med olika egenskaper leder till tvingande cykling, där varje deklaration framtvingar ett inkompatibelt tillstånd för instansen vid varje körning.

Hämta det aktuella tillståndet för en konfiguration

Kommandot dsc config get hämtar det aktuella tillståndet för de resursinstanser som definierats i ett konfigurationsdokument. När du använder det här kommandot gör DSC även följande:

  • Samlar in alla meddelanden som genereras av resurserna under åtgärden.
  • Anger om någon av resurserna utlöste ett fel.
  • Innehåller metadata om åtgärden som helhet och för varje resursinstans.
dsc config get --file ./example.config.dsc.yaml

metadata:
  Microsoft.DSC:
    version: 3.0.0
    operation: get
    executionType: actual
    startDatetime: 2025-02-24T16:09:40.671454400-06:00
    endDatetime: 2025-02-24T16:09:41.850086300-06:00
    duration: PT1.1786319S
    securityContext: restricted
results:
- metadata:
    Microsoft.DSC:
      duration: PT0.2751153S
  name: example key value
  type: Microsoft.Windows/Registry
  result:
    actualState:
      keyPath: HKCU\example\key
      _exist: false
messages: []
hadErrors: false

Testa en konfiguration

Kommandot dsc config test jämför det aktuella tillståndet för resursinstanserna med deras önskade tillstånd. Resultatet för varje instans inkluderar:

  • Det önskade tillståndet för instansen.
  • Det faktiska tillståndet för instansen.
  • Om instansen är i önskat tillstånd.
  • Listan över egenskaper som inte har det önskade tillståndet, om det finns några.

När du använder det här kommandot gör DSC även följande:

  • Samlar in alla meddelanden som genereras av resurserna under åtgärden.
  • Anger om någon av resurserna utlöste ett fel.
  • Innehåller metadata om åtgärden som helhet och för varje resursinstans.
dsc config test --file /example.config.dsc.yaml

metadata:
  Microsoft.DSC:
    version: 3.0.0
    operation: test
    executionType: actual
    startDatetime: 2025-02-24T16:11:42.798122500-06:00
    endDatetime: 2025-02-24T16:11:43.442216400-06:00
    duration: PT0.6440939S
    securityContext: restricted
results:
- metadata:
    Microsoft.DSC:
      duration: PT0.2234078S
  name: example key value
  type: Microsoft.Windows/Registry
  result:
    desiredState:
      keyPath: HKCU\example\key
      valueName: Example
      valueData:
        String: This is an example.
    actualState:
      keyPath: HKCU\example\key
      _exist: false
    inDesiredState: false
    differingProperties:
    - valueName
    - valueData
    - _exist
messages: []
hadErrors: false

Framtvinga en konfiguration

Kommandot dsc config set tvingar de resursinstanser som definierats i ett konfigurationsdokument till önskat tillstånd. Resultatet för varje instans inkluderar:

  • Tillståndet för instansen före åtgärden.
  • Tillståndet för instansen efter åtgärden.
  • Vilka egenskaper som åtgärden har ändrat, om det finns några.

När du använder det här kommandot gör DSC även följande:

  • Samlar in alla meddelanden som genereras av resurserna under åtgärden.
  • Anger om någon av resurserna utlöste ett fel.
  • Innehåller metadata om åtgärden som helhet och för varje resursinstans.
dsc config set --file ./example.config.dsc.yaml

metadata:
  Microsoft.DSC:
    version: 3.0.0
    operation: set
    executionType: actual
    startDatetime: 2025-02-24T16:13:32.746742600-06:00
    endDatetime: 2025-02-24T16:13:33.606785-06:00
    duration: PT0.8600424S
    securityContext: restricted
results:
- metadata:
    Microsoft.DSC:
      duration: PT0.4070001S
  name: example key value
  type: Microsoft.Windows/Registry
  result:
    beforeState:
      keyPath: HKCU\example\key
      _exist: false
    afterState:
      keyPath: HKCU\example\key
      valueName: Example
      valueData:
        String: This is an example.
    changedProperties:
    - valueName
    - valueData
    - _exist
messages: []
hadErrors: false

Se även