Delen via

Anatomie van een DSC-resource op basis van opdrachten

  • Artikel

DSC-resources bieden een gestandaardiseerde interface voor het beheren van de instellingen van een systeem. Een resource definieert eigenschappen die u kunt beheren en implementeert de code die nodig is om een exemplaar van de resource op te halen.

DSC-resources op basis van opdrachten worden gedefinieerd met ten minste twee bestanden:

  1. Een DSC-resourcemanifest waarmee DSC wordt aangegeven hoe de resource moet worden gebruikt.
  2. Een of meer uitvoerbare bestanden en de bijbehorende afhankelijkheden voor het beheren van exemplaren van de resource.

DSC-resourcemanifesten

DSC-resourcemanifesten worden gedefinieerd als JSON-bestanden. Dsc kan een JSON-bestand alleen herkennen als een manifest als het bestand aan de volgende criteria voldoet:

  1. Het bestand moet detecteerbaar zijn in de PATH omgevingsvariabele.
  2. De bestandsnaam moet eindigen op .dsc.resource.json.

Wanneer DSC in het lokale systeem zoekt naar beschikbare DSC-resources op basis van opdrachten, wordt in elke map in de PATH gezocht naar bestanden die gebruikmaken van de naamconventie voor het DSC-resourcemanifest. DSC parseert vervolgens elk van deze gedetecteerde bestanden en valideert deze op basis van het JSON-schema dsc-resourcemanifest.

Als het JSON-bestand wordt gevalideerd op basis van het schema, kan DSC de DSC-resource gebruiken.

Het manifest moet ten minste het volgende definiëren:

  • De versie van het JSON-schema dsc-resourcemanifest waarmee deze compatibel is.
  • De volledig gekwalificeerde naam van de resource, zoals Microsoft.Windows/Registry. De volledig gekwalificeerde naamsyntaxis is <owner>[.<group>][.<area>]/<name>. Met de groeps- en gebiedsonderdelen van de volledig gekwalificeerde naam kunt u resources ordenen in naamruimten.
  • Hoe DSC de opdracht kan aanroepen om de huidige status van een resource-exemplaar op te halen.
  • Een manier om een exemplaar te valideren. Dit kan een van de volgende zijn:
    • Een JSON-schema waarin een exemplaar wordt beschreven
    • Een opdracht DSC moet aanroepen om het schema tijdens runtime op te halen
    • Een opdracht voor het valideren van geneste DSC-resources. Deze laatste optie is alleen van toepassing op DSC-groepsresources en DSC-providerresources.

Het manifest kan eventueel het volgende definiëren:

  • Hoe DSC de opdracht kan aanroepen om te testen of een exemplaar de gewenste status heeft.
  • Hoe DSC de opdracht kan aanroepen om een exemplaar in te stellen op de gewenste status.
  • De betekenis van de niet-nul afsluitcodes die door de opdracht worden geretourneerd.
  • Hoe DSC de opdracht kan aanroepen om andere DSC-resources te beheren, wanneer de resource een DSC-groepsresource of een DSC-providerresource is.
  • Metagegevens over de resource, zoals de auteur en een korte beschrijving.

Als het manifest niet definieert hoe een exemplaar van de resource moet worden getest, voert DSC een synthetische test uit voor resource-exemplaren. De synthetische test van DSC haalt altijd de werkelijke status van een exemplaar op en vergelijkt de eigenschappen van het exemplaar strikt met de gewenste status. De synthetische test negeert alle eigenschappen die zijn voorafgegaan door een onderstrepingsteken (_) of dollarteken ($). Als een van de eigenschappen niet exact hetzelfde is als de gedefinieerde gewenste status, rapporteert DSC dat het exemplaar niet-compatibel is.

Als het manifest niet definieert hoe een exemplaar van de DSC-resource moet worden ingesteld, kan DSC de resource niet gebruiken om de gewenste status af te dwingen.

Het manifest hoeft niet voor elke bewerking hetzelfde uitvoerbare bestand op te geven. De definitie voor elke bewerking is onafhankelijk.

Uitvoerbare bestanden van DSC-resource

DSC-resources op basis van opdrachten vereisen altijd een uitvoerbaar bestand om DSC uit te voeren. Het DSC-resourcemanifest hoeft niet te worden gebundeld met het uitvoerbare bestand. Het uitvoerbare bestand kan elk uitvoerbaar bestand zijn, zoals een binaire toepassing of een shellscript. Een resource kan verschillende uitvoerbare bestanden gebruiken voor verschillende bewerkingen.

DSC kan alleen een uitvoerbaar bestand gebruiken als het kan worden gedetecteerd in de PATH omgevingsvariabele. DSC roept het uitvoerbare bestand eenmaal per bewerking aan met behulp van de afsluitcode die wordt geretourneerd door het uitvoerbare bestand om te bepalen of de opdracht is geslaagd. DSC behandelt afsluitcode 0 als een geslaagde code en alle andere afsluitcodes als een fout.

Invoerwaarden

DSC verzendt invoer naar dsc-resources op basis van opdrachten als een JSON-gegevensblob via stdin of als een set argumentvlagmen en -waarden. Invoerafhandeling wordt per bewerking gedefinieerd in het DSC-resourcemanifest.

Wanneer DSC de invoer als JSON verzendt via stdin, is de gegevensblob de JSON-weergave van de gewenste status van een exemplaar. Dit is de meest robuuste optie voor een resource, omdat de resource hiermee complexe eigenschappen met geneste objecten kan ondersteunen.

Wanneer DSC de invoer als argumenten verzendt, genereert het een paar argumenten voor elk van de opgegeven eigenschappen. Het eerste argument is de naam van de eigenschap met het voorvoegsel --, zoals --duration. Het tweede argument is de waarde van de eigenschap. De volgorde van de argumentparen wordt niet gegarandeerd. Deze invoermethode biedt geen ondersteuning voor complexe eigenschappen.

Uitvoerwaarden

Het uitvoerbare bestand voor een DSC-resource op basis van opdrachten moet JSON-gegevens retourneren naar stdout wanneer deze wordt aangeroepen door DSC. De uitvoercodering moet UTF-8 zijn. Wanneer de resource de status van een exemplaar retourneert, valideert DSC de JSON-gegevens op basis van het exemplaarschema van de resource.

Voor DSC-providerresources verwacht DSC dat het uitvoerbare bestand de instantiestatussen doorgeeft voor de resources die worden beheerd als één JSON-matrix of als een reeks JSON-lijnen.

DSC-resources op basis van opdrachten kunnen logboekregistratiegegevens rapporteren aan DSC door JSON-lijnen naar stderr te verzenden. Elke logboekvermelding moet een JSON-object zijn dat twee sleutels bevat:

  1. De message sleutel definieert de door mensen leesbare tekenreeks voor de logboekvermelding.
  2. De level sleutel bepaalt of het bericht een Error, een Warningof Informationvertegenwoordigt.

DSC verzamelt berichten van resources en geeft deze weer in de resultaten van een configuratiebewerking. Wanneer DSC een resource direct buiten een configuratie aanroept, worden de berichten niet verzameld. In plaats daarvan worden ze alleen verzonden naar Stderr.

Gerelateerde inhoud