Dela via

Anatomi för en kommandobaserad DSC-resurs

DSC-resurser tillhandahåller ett standardiserat gränssnitt för att hantera inställningarna i ett system. En resurs definierar egenskaper som du kan hantera och implementerar den kod som behövs för att hämta en instans av resursen.

DSC-kommandoresurser definieras med minst två filer:

  1. Ett DSC-resursmanifest som talar om för DSC hur du interagerar med resursen.
  2. En eller flera körbara filer och deras beroenden för att hantera instanser av resursen.

Manifest för DSC-resurser

DSC-resursmanifest definieras som datafiler. För att DSC ska kunna känna igen en datafil som ett manifest måste filen uppfylla följande kriterier:

  1. Data i filen måste vara formaterade som YAML eller JSON.

  2. Filen måste använda UTF-8-kodning.

  3. Filen måste kunna identifieras i miljövariabeln PATH .

  4. Filnamnet måste sluta med något av följande suffix:

    • .dsc.resource.json
    • .dsc.resource.yaml
    • .dsc.resource.yml

När DSC söker i det lokala systemet efter tillgängliga kommandoresurser söker den igenom varje mapp efter PATH filer som använder namngivningskonventionen för DSC-resursmanifestet. DSC parsar sedan var och en av de identifierade filerna och validerar dem mot JSON-schemat för DSC-resursmanifestet.

Om JSON-filen verifieras mot schemat kan DSC använda DSC-resursen.

Manifestet måste minst definiera:

  • Den version av JSON-schemat för DSC-resursmanifestet som den är kompatibel med.
  • Det fullständigt kvalificerade namnet på resursen, till exempel Microsoft.Windows/Registry. Den fullständigt kvalificerade namnsyntaxen är <owner>[.<group>][.<area>]/<name>. Grupp- och områdeskomponenterna i det fullständigt kvalificerade namnet gör det möjligt att organisera resurser i namnområden.
  • Hur DSC kan anropa kommandot för att hämta det aktuella tillståndet för en resursinstans.
  • Ett sätt att validera en instans. Alternativen för att verifiera en instans är:
    • Ett JSON-schema som beskriver en instans
    • Ett kommando som DSC måste anropa för att hämta schemat vid körning
    • Ett kommando för att verifiera kapslade DSC-resurser. Det sista alternativet gäller endast för DSC-gruppresurser och DSC-kortresurser.

Manifestet kan definiera:

  • Den typ av resurs som manifestet beskriver: adapter, group, importer, eller resource.

    Om manifestet inte definierar resurstypen används resource som standard och tolkas det som en typisk resurs som direkt hanterar en instans.

  • Hur DSC kan anropa kommandot för att testa om en instans är i önskat tillstånd.

    Om manifestet inte definierar hur en instans av resursen ska testas utför DSC ett syntetiskt test för resursinstanser. DSC:s syntetiska test hämtar alltid det faktiska tillståndet för en instans och gör en strikt skiftlägeskänslig jämförelse av instansens egenskaper till det önskade tillståndet. Om någon av egenskaperna inte är exakt samma som det definierade önskade tillståndet rapporterar DSC instansen som icke-kompatibel.

  • Hur DSC kan anropa kommandot för att ställa in en instans på önskat tillstånd.

    Om manifestet inte definierar hur du anger en instans av DSC-resursen kan DSC inte använda resursen för att framtvinga önskat tillstånd.

  • Innebörden av slutkoderna som inte är noll som returneras av kommandot.

    Om manifestet inte definierar innebörden av slutkoder rapporteras alla slutkoder som inte är noll som ett allmänt fel.

  • Hur DSC kan anropa kommandot för att exportera en lista över varje instans av resursen på datorn.

  • Hur DSC kan anropa kommandot för att ta bort en specifik instans av resursen.

  • Metadata om resursen, till exempel dess författare och en kort beskrivning.

Manifestet behöver inte ange samma körbara fil för varje åtgärd. Definitionen för varje åtgärd är oberoende.

Körbara filer för DSC-resurser

Kommandoresurser kräver alltid en körbar fil för att DSC ska kunna köras. Manifestet behöver inte paketeras med den körbara filen. Den körbara filen kan vara vilken körbar fil som helst, till exempel ett binärt program eller ett skalskript. En resurs kan använda olika körbara filer för olika åtgärder.

För att DSC ska kunna använda en körbar fil måste den kunna identifieras i miljövariabeln PATH . DSC anropar den körbara filen en gång per åtgärd med hjälp av slutkoden som returneras av den körbara filen för att avgöra om kommandot lyckades. DSC behandlar slutkoden 0 som en framgång och alla andra slutkoder som ett fel.

Ingångar

DSC skickar indata till kommandoresurser på något av följande sätt:

  • En JSON-datablob över stdin.

    När DSC skickar indata som JSON över stdin är databloben JSON-representationen av en instanss önskade tillstånd. Det här inmatningsalternativet stöder komplexa egenskaper med kapslade objekt.

  • En JSON-datablob som värde för ett specifikt argument.

    När resursen definierar ett JSON-indataargument anropar DSC kommandot med det definierade argumentet och skickar JSON-representationen av en instanss önskade tillstånd till det argumentet. Det här inmatningsalternativet stöder komplexa egenskaper med kapslade objekt.

  • En uppsättning argumentflaggor och värden.

    När DSC skickar indata som argument genererar den ett par argument för var och en av de angivna egenskaperna. Det första argumentet är namnet på egenskapen som föregås --av , till exempel --duration. Det andra argumentet är egenskapens värde. Ordningen på argumentparen är inte garanterad. Den här indatametoden stöder inte komplexa egenskaper.

  • Miljövariabler.

    När DSC skickar indata som miljövariabler definierar den en miljövariabel för varje egenskap i resursinstansen och anger värdet till strängrepresentationen av den egenskapen. Dessa miljövariabler definieras endast för körning av kommandot för den specifika åtgärden. Miljövariablerna påverkar inte några andra processer.

Indatahantering definieras per åtgärd i resursmanifestet. En resurs kan definiera olika indatahantering för de åtgärder som den stöder.

Utdata

Den körbara filen för en kommandoresurs måste returnera JSON-data till stdout när den anropas av DSC. Utdatakodningen måste vara UTF-8. När resursen returnerar tillståndet för en instans verifierar DSC JSON-data mot resursens instansschema.

För adapterresurser förväntar sig DSC att den körbara filen passerar genom instanstillstånden för de resurser som den hanterar som antingen en enda JSON-matris eller som en serie JSON-linjer.

Kommandoresurser kan rapportera loggningsinformation till DSC genom att skicka JSON-rader till stderr. Varje loggpost måste vara ett JSON-objekt som innehåller två nycklar:

  1. Nyckeln message definierar den läsbara strängen för loggposten.
  2. Nyckeln level definierar om meddelandet representerar en error, en warningeller information.

DSC samlar in meddelanden från resurser och visar dem i resultatet för en konfigurationsåtgärd. När DSC anropar en resurs direkt utanför en konfiguration samlar den inte in meddelandena. I stället skickar DSC meddelandena till stderr.

Relaterat innehåll