Delen via

Een aangepaste DSC-resource schrijven met MOF

  • Artikel

Van toepassing op: Windows PowerShell 4.0, Windows PowerShell 5.0

In dit artikel definiëren we het schema voor een aangepaste dsc-resource (Windows PowerShell Desired State Configuration) in een MOF-bestand en implementeren we de resource in een Windows PowerShell scriptbestand. Deze aangepaste resource is bedoeld voor het maken en onderhouden van een website.

Het MOF-schema maken

Het schema definieert de eigenschappen van uw resource die kunnen worden geconfigureerd door een DSC-configuratiescript.

Mapstructuur voor een MOF-resource

Als u een aangepaste DSC-resource met een MOF-schema wilt implementeren, maakt u de volgende mapstructuur. Het MOF-schema wordt gedefinieerd in het bestand Demo_IISWebsite.schema.mofen het resourcescript wordt gedefinieerd in Demo_IISWebsite.psm1. U kunt desgewenst een modulemanifestbestand (psd1) maken.

$env:ProgramFiles\WindowsPowerShell\Modules (folder)
    |- MyDscResources (folder)
        |- MyDscResources.psd1 (file, required)
        |- DSCResources (folder)
            |- Demo_IISWebsite (folder)
                |- Demo_IISWebsite.psd1 (file, optional)
                |- Demo_IISWebsite.psm1 (file, required)
                |- Demo_IISWebsite.schema.mof (file, required)

Notitie

Het is noodzakelijk om een map met de naam DSCResources onder de map op het hoogste niveau te maken en dat de map voor elke resource dezelfde naam moet hebben als de resource.

De inhoud van het MOF-bestand

Hieronder volgt een voorbeeld van een MOF-bestand dat kan worden gebruikt voor een aangepaste websiteresource. Als u dit voorbeeld wilt volgen, slaat u dit schema op in een bestand en roept u het bestand Demo_IISWebsite.schema.mofaan.

[ClassVersion("1.0.0"), FriendlyName("Website")]
class Demo_IISWebsite : OMI_BaseResource
{
  [Key] string Name;
  [Required] string PhysicalPath;
  [write,ValueMap{"Present", "Absent"},Values{"Present", "Absent"}] string Ensure;
  [write,ValueMap{"Started","Stopped"},Values{"Started", "Stopped"}] string State;
  [write] string Protocol[];
  [write] string BindingInfo[];
  [write] string ApplicationPool;
  [read] string ID;
};

Let op het volgende over de vorige code:

  • FriendlyName definieert de naam die u kunt gebruiken om te verwijzen naar deze aangepaste resource in DSC-configuratiescripts. In dit voorbeeld Website is gelijk aan de beschrijvende naam Archive voor de ingebouwde archiefresource.
  • De klasse die u voor uw aangepaste resource definieert, moet zijn afgeleid van OMI_BaseResource.
  • De typekwalificatie, [Key], voor een eigenschap geeft aan dat deze eigenschap het resource-exemplaar uniek identificeert. Er is ten minste één [Key] eigenschap vereist.
  • De [Required] kwalificatie geeft aan dat de eigenschap vereist is (een waarde moet worden opgegeven in een configuratiescript dat gebruikmaakt van deze resource).
  • De [write] kwalificatie geeft aan dat deze eigenschap optioneel is bij het gebruik van de aangepaste resource in een configuratiescript. De [read] kwalificatie geeft aan dat een eigenschap niet kan worden ingesteld door een configuratie en is alleen voor rapportagedoeleinden.
  • Values beperkt de waarden die kunnen worden toegewezen aan de eigenschap tot de lijst met waarden die zijn gedefinieerd in ValueMap. Zie ValueMap en Value Qualifiers voor meer informatie.
  • Het opnemen van een eigenschap met de naam Ensure waarden Present en Absent in uw resource wordt aanbevolen als een manier om een consistente stijl te behouden met ingebouwde DSC-resources.
  • Geef het schemabestand voor uw aangepaste resource de volgende naam: classname.schema.mof, waarbij classname de id is die het trefwoord in uw class schemadefinitie volgt.

Het resourcescript schrijven

Met het resourcescript wordt de logica van de resource geïmplementeerd. In deze module moet u drie functies opnemen met de naam Get-TargetResource, Set-TargetResourceen Test-TargetResource. Alle drie de functies moeten een parameterset hebben die identiek is aan de set eigenschappen die is gedefinieerd in het MOF-schema dat u voor uw resource hebt gemaakt. In dit document wordt deze set eigenschappen aangeduid als de 'resource-eigenschappen'. Sla deze drie functies op in een bestand met de naam <ResourceName>.psm1. In het volgende voorbeeld worden de functies opgeslagen in een bestand met de naam Demo_IISWebsite.psm1.

Notitie

Wanneer u hetzelfde configuratiescript meerdere keren op uw resource uitvoert, ontvangt u geen fouten en moet de resource in dezelfde status blijven als het uitvoeren van het script. Om dit te bereiken, moet u ervoor zorgen dat de Get-TargetResource functies en Test-TargetResource de resource ongewijzigd blijven en dat het meerdere keren aanroepen van de Set-TargetResource functie in een reeks met dezelfde parameterwaarden altijd gelijk is aan het eenmaal aanroepen ervan.

Gebruik in de functie-implementatie Get-TargetResource de waarden van de sleutelresource-eigenschap die als parameters worden opgegeven om de status van het opgegeven resource-exemplaar te controleren. Deze functie moet een hash-tabel retourneren met alle resource-eigenschappen als sleutels en de werkelijke waarden van deze eigenschappen als de bijbehorende waarden. De volgende code biedt een voorbeeld.

# DSC uses the Get-TargetResource function to fetch the status of the resource instance
# specified in the parameters for the target machine
function Get-TargetResource
{
    param
    (
        [ValidateSet("Present", "Absent")]
        [string]$Ensure = "Present",

        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$Name,

        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$PhysicalPath,

        [ValidateSet("Started", "Stopped")]
        [string]$State = "Started",

        [string]$ApplicationPool,

        [string[]]$BindingInfo,

        [string[]]$Protocol
    )

        $getTargetResourceResult = $null;

        <#
          Insert logic that uses the mandatory parameter values to get the website and
          assign it to a variable called $Website
          Set $ensureResult to "Present" if the requested website exists and to "Absent" otherwise
        #>

        # Add all Website properties to the hash table
        # This simple example assumes that $Website is not null
        $getTargetResourceResult = @{
            Name = $Website.Name
            Ensure = $ensureResult
            PhysicalPath = $Website.physicalPath
            State = $Website.state
            ID = $Website.id
            ApplicationPool = $Website.applicationPool
            Protocol = $Website.bindings.Collection.protocol
            Binding = $Website.bindings.Collection.bindingInformation
        }

        $getTargetResourceResult
}

Afhankelijk van de waarden die zijn opgegeven voor de resource-eigenschappen in het configuratiescript, moet de Set-TargetResource een van de volgende handelingen uitvoeren:

  • Een nieuwe website maken
  • Een bestaande website bijwerken
  • Een bestaande website verwijderen

In het volgende voorbeeld ziet u dit.

# The Set-TargetResource function is used to create, delete or configure a website on the target machine.
function Set-TargetResource
{
    [CmdletBinding(SupportsShouldProcess=$true)]
    param
    (
        [ValidateSet("Present", "Absent")]
        [string]$Ensure = "Present",

        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$Name,

        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$PhysicalPath,

        [ValidateSet("Started", "Stopped")]
        [string]$State = "Started",

        [string]$ApplicationPool,

        [string[]]$BindingInfo,

        [string[]]$Protocol
    )

    <#
        If Ensure is set to "Present" and the website specified in the mandatory input parameters
          does not exist, then create it using the specified parameter values
        Else, if Ensure is set to "Present" and the website does exist, then update its properties
          to match the values provided in the non-mandatory parameter values
        Else, if Ensure is set to "Absent" and the website does not exist, then do nothing
        Else, if Ensure is set to "Absent" and the website does exist, then delete the website
    #>
}

Ten slotte moet de Test-TargetResource functie dezelfde parameterset hebben als Get-TargetResource en Set-TargetResource. Controleer in uw implementatie van Test-TargetResourcede status van het resource-exemplaar dat is opgegeven in de sleutelparameters. Als de werkelijke status van het resource-exemplaar niet overeenkomt met de waarden die zijn opgegeven in de parameterset, retourneert $falseu . Anders retourneert $trueu .

Met de volgende code wordt de Test-TargetResource functie geïmplementeerd.

function Test-TargetResource
{
    [CmdletBinding()]
    [OutputType([System.Boolean])]
    param
    (
        [ValidateSet("Present","Absent")]
        [System.String]
        $Ensure,

        [parameter(Mandatory = $true)]
        [System.String]
        $Name,

        [parameter(Mandatory = $true)]
        [System.String]
        $PhysicalPath,

        [ValidateSet("Started","Stopped")]
        [System.String]
        $State,

        [System.String[]]
        $Protocol,

        [System.String[]]
        $BindingData,

        [System.String]
        $ApplicationPool
    )

    # Get the current state
    $currentState = Get-TargetResource -Ensure $Ensure -Name $Name -PhysicalPath $PhysicalPath -State $State -ApplicationPool $ApplicationPool -BindingInfo $BindingInfo -Protocol $Protocol

    # Write-Verbose "Use this cmdlet to deliver information about command processing."

    # Write-Debug "Use this cmdlet to write debug information while troubleshooting."

    # Include logic to
    $result = [System.Boolean]
    # Add logic to test whether the website is present and its status matches the supplied
    # parameter values. If it does, return true. If it does not, return false.
    $result
}

Notitie

Voor eenvoudigere foutopsporing gebruikt u de Write-Verbose cmdlet in uw implementatie van de vorige drie functies. Deze cmdlet schrijft tekst naar de uitgebreide berichtenstroom. Standaard wordt de uitgebreide berichtenstroom niet weergegeven, maar u kunt deze weergeven door de waarde van de variabele $VerbosePreference te wijzigen of door de parameter Uitgebreid in de DSC-cmdlets = nieuw te gebruiken.

Het modulemanifest maken

Gebruik ten slotte de New-ModuleManifest cmdlet om een <ResourceName>.psd1 bestand voor uw aangepaste resourcemodule te definiëren. Wanneer u deze cmdlet aanroept, verwijst u naar het scriptmodulebestand (.psm1) dat in de vorige sectie wordt beschreven. Neem Get-TargetResource, Set-TargetResourceen Test-TargetResource op in de lijst met functies die u wilt exporteren. Hier volgt een voorbeeld van een manifestbestand.

# Module manifest for module 'Demo.IIS.Website'
#
# Generated on: 1/10/2013
#

@{

# Script module or binary module file associated with this manifest.
# RootModule = ''

# Version number of this module.
ModuleVersion = '1.0'

# ID used to uniquely identify this module
GUID = '6AB5ED33-E923-41d8-A3A4-5ADDA2B301DE'

# Author of this module
Author = 'Contoso'

# Company or vendor of this module
CompanyName = 'Contoso'

# Copyright statement for this module
Copyright = 'Contoso. All rights reserved.'

# Description of the functionality provided by this module
Description = 'This Module is used to support the creation and configuration of IIS Websites through Get, Set and Test API on the DSC managed nodes.'

# Minimum version of the Windows PowerShell engine required by this module
PowerShellVersion = '4.0'

# Minimum version of the common language runtime (CLR) required by this module
CLRVersion = '4.0'

# Modules that must be imported into the global environment prior to importing this module
RequiredModules = @("WebAdministration")

# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
NestedModules = @("Demo_IISWebsite.psm1")

# Functions to export from this module
FunctionsToExport = @("Get-TargetResource", "Set-TargetResource", "Test-TargetResource")

# Cmdlets to export from this module
#CmdletsToExport = '*'

# HelpInfo URI of this module
# HelpInfoURI = ''
}

Ondersteuning voor PsDscRunAsCredential

Notitie

PsDscRunAsCredential wordt ondersteund in PowerShell 5.0 en hoger.

De eigenschap PsDscRunAsCredential kan worden gebruikt in het resourceblok DSC-configuraties om op te geven dat de resource moet worden uitgevoerd onder een opgegeven set referenties. Zie DSC uitvoeren met gebruikersreferenties voor meer informatie.

Als u toegang wilt krijgen tot de gebruikerscontext vanuit een aangepaste resource, kunt u de automatische variabele $PsDscContextgebruiken.

De volgende code schrijft bijvoorbeeld de gebruikerscontext waaronder de resource wordt uitgevoerd naar de uitgebreide uitvoerstroom:

if (PsDscContext.RunAsUser) {
    Write-Verbose "User: $PsDscContext.RunAsUser";
}

Het knooppunt opnieuw opstarten

Als de acties in uw Set-TargetResource functie opnieuw moeten worden opgestart, kunt u een globale vlag gebruiken om de LCM te laten weten dat het knooppunt opnieuw moet worden opgestart. Deze herstart vindt direct plaats nadat de Set-TargetResource functie is voltooid.

Voeg in uw Set-TargetResource functie de volgende regel code toe.

# Include this line if the resource requires a system reboot.
$global:DSCMachineStatus = 1

Om ervoor te zorgen dat de LCM het knooppunt opnieuw kan opstarten, moet de vlag RebootNodeIfNeeded worden ingesteld op $true. De instelling ActionAfterReboot moet ook worden ingesteld op ContinueConfiguration. Dit is de standaardinstelling. Zie De lokale Configuration Manager configureren of De lokale Configuration Manager(v4) configureren voor meer informatie over het configureren van de LCM.