Schrijven van een aangepaste DSC-resource met MOFWriting a custom DSC resource with MOF

Van toepassing op: Windows PowerShell 4.0, Windows PowerShell 5.0Applies To: Windows PowerShell 4.0, Windows PowerShell 5.0

In dit onderwerp wordt het schema voor de aangepaste resource van een Windows PowerShell Desired State Configuration (DSC) definiëren in een MOF-bestand, en implementeren van de resource in een Windows PowerShell-scriptbestand.In this topic, we will define the schema for a Windows PowerShell Desired State Configuration (DSC) custom resource in a MOF file, and implement the resource in a Windows PowerShell script file. Deze aangepaste resource wordt voor het maken en onderhouden van een website.This custom resource is for creating and maintaining a web site.

Maken van het MOF-schemaCreating the MOF schema

Het schema definieert de eigenschappen van de bron die kunnen worden geconfigureerd door een DSC-configuratiescript.The schema defines the properties of your resource that can be configured by a DSC configuration script.

Mapstructuur voor een MOF-bronFolder structure for a MOF resource

Voor het implementeren van een aangepaste DSC-resource met een MOF-schema, maken de volgende mapstructuur.To implement a DSC custom resource with a MOF schema, create the following folder structure. Het MOF-schema is gedefinieerd in het bestand Demo_IISWebsite.schema.mof en het resource-script is gedefinieerd in Demo_IISWebsite.psm1.The MOF schema is defined in the file Demo_IISWebsite.schema.mof, and the resource script is defined in Demo_IISWebsite.psm1. U kunt desgewenst een module-manifest (psd1)-bestand maken.Optionally, you can create a module manifest (psd1) file.

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

Houd er rekening mee dat het nodig zijn voor het maken van een map met de naam DSCResources onder de hoofdmap is en dat de map voor elke resource moet dezelfde naam als de bron.Note that it is necessary to create a folder named DSCResources under the top-level folder, and that the folder for each resource must have the same name as the resource.

De inhoud van het MOF-bestandThe contents of the MOF file

Hier volgt een voorbeeld van de MOF-bestand dat kan worden gebruikt voor de bron van een aangepaste website.Following is an example MOF file that can be used for a custom website resource. Wilt u dit voorbeeld, dit schema opslaan in een bestand en het bestand Demo_IISWebsite.schema.mof.To follow this example, save this schema to a file, and call the file Demo_IISWebsite.schema.mof.

[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;
};

Houd rekening met de volgende met betrekking tot de vorige code:Note the following about the previous code:

  • FriendlyName definieert de naam die u gebruiken kunt om te verwijzen naar deze aangepaste resource in scripts voor DSC-configuratie.FriendlyName defines the name you can use to refer to this custom resource in DSC configuration scripts. In dit voorbeeld Website komt overeen met de beschrijvende naam Archive voor de ingebouwde archief-resource.In this example, Website is equivalent to the friendly name Archive for the built-in Archive resource.
  • De klasse die u definieert voor de aangepaste resource moet worden afgeleid van OMI_BaseResource.The class you define for your custom resource must derive from OMI_BaseResource.
  • De kwalificatie type [Key]op een eigenschap aangeeft dat deze eigenschap een unieke identificatie van de resource-instantie.The type qualifier, [Key], on a property indicates that this property will uniquely identify the resource instance. Ten minste één [Key] eigenschap is vereist.At least one [Key] property is required.
  • De [Required] kwalificatie geeft aan dat de eigenschap vereist is (er moet een waarde worden opgegeven in een configuratiescript dat gebruikmaakt van deze bron).The [Required] qualifier indicates that the property is required (a value must be specified in any configuration script that uses this resource).
  • De [write] kwalificatie geeft aan dat deze eigenschap optioneel is bij het gebruik van de aangepaste resource in een configuratiescript.The [write] qualifier indicates that this property is optional when using the custom resource in a configuration script. De [read] kwalificatie geeft aan dat een eigenschap kan niet worden ingesteld door een configuratie en is alleen voor rapportagedoeleinden.The [read] qualifier indicates that a property cannot be set by a configuration, and is for reporting purposes only.
  • Values Hiermee beperkt u de waarden die kunnen worden toegewezen aan de eigenschap aan de lijst met waarden die zijn gedefinieerd in ValueMap.Values restricts the values that can be assigned to the property to the list of values defined in ValueMap. Zie voor meer informatie ValueMap en waarde-kwalificaties bevat.For more information, see ValueMap and Value Qualifiers.
  • Met inbegrip van een eigenschap genaamd Ensure met waarden Present en Absent in de bron, wordt aanbevolen als een manier om een consistente stijl met ingebouwde DSC-resources te onderhouden.Including a property called Ensure with values Present and Absent in your resource is recommended as a way to maintain a consistent style with built-in DSC resources.
  • Naam van het schemabestand voor uw aangepaste resource als volgt: classname.schema.mof, waarbij classname is de id die volgt de class -sleutelwoord in de schemadefinitie van de.Name the schema file for your custom resource as follows: classname.schema.mof, where classname is the identifier that follows the class keyword in your schema definition.

De resource-script schrijvenWriting the resource script

Het script resource implementeert de logica van de resource.The resource script implements the logic of the resource. U moet drie functies aangeroepen opnemen in deze module Get-TargetResource, Set TargetResource, en Test TargetResource.In this module, you must include three functions called Get-TargetResource, Set-TargetResource, and Test-TargetResource. Alle drie functies moeten rekening houden met een parameterset die identiek is aan de set eigenschappen die zijn gedefinieerd in het MOF-schema dat u hebt gemaakt voor uw resource.All three functions must take a parameter set that is identical to the set of properties defined in the MOF schema that you created for your resource. In dit document, wordt deze reeks eigenschappen aangeduid als de "broneigenschappen'.In this document, this set of properties is referred to as the “resource properties.” Deze drie functies in een bestand genaamd Store .psm1.Store these three functions in a file called .psm1. In het volgende voorbeeld worden de functies worden opgeslagen in een bestand met de naam Demo_IISWebsite.psm1.In the following example, the functions are stored in a file called Demo_IISWebsite.psm1.

Opmerking: wanneer u de dezelfde configuratiescript op uw resource meer dan één keer uitvoeren, u geen fouten ontvangt en de bron in dezelfde staat blijven moet als het eenmaal uitvoeren van het script.Note: When you run the same configuration script on your resource more than once, you should receive no errors and the resource should remain in the same state as running the script once. U doet dit door ervoor te zorgen dat uw Get-TargetResource en Test TargetResource functies laat de bron niet worden gewijzigd en dat aanroepen van de Set-TargetResourcewerken meer dan één keer in een reeks met dezelfde parameter waarden is altijd gelijk is aan één keer aangeroepen.To accomplish this, ensure that your Get-TargetResource and Test-TargetResource functions leave the resource unchanged, and that invoking the Set-TargetResource function more than once in a sequence with the same parameter values is always equivalent to invoking it once.

In de Get-TargetResource implementatie werkt, de belangrijkste bron eigenschapswaarden die beschikbaar zijn als parameters gebruiken om te controleren van de status van het exemplaar van de opgegeven bron.In the Get-TargetResource function implementation, use the key resource property values that are provided as parameters to check the status of the specified resource instance. Deze functie moet een hashtabel waarin de broneigenschappen als sleutels en de werkelijke waarden van deze eigenschappen als de bijbehorende waarden retourneren.This function must return a hash table that lists all the resource properties as keys and the actual values of these properties as the corresponding values. De volgende code geeft een voorbeeld.The following code provides an example.

# 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 de Set TargetResource moet een van de volgende dingen doen:Depending on the values that are specified for the resource properties in the configuration script, the Set-TargetResource must do one of the following:

  • Een nieuwe website makenCreate a new website
  • Bijwerken van een bestaande websiteUpdate an existing website
  • Verwijderen van een bestaande websiteDelete an existing website

Het volgende voorbeeld ziet u dit.The following example illustrates this.

# 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 de Test TargetResource functie moet rekening houden met dezelfde parameterset als Get-TargetResource en Set TargetResource.Finally, the Test-TargetResource function must take the same parameter set as Get-TargetResource and Set-TargetResource. Bij de implementatie van Test TargetResource, Controleer de status van de resource-instantie die is opgegeven in de belangrijkste parameters.In your implementation of Test-TargetResource, check the status of the resource instance that is specified in the key parameters. Als de huidige status van het exemplaar van de resource komt niet overeen met de opgegeven waarden in de parameterset, geretourneerd $false.If the actual status of the resource instance does not match the values specified in the parameter set, return $false. Anders retourneren $true.Otherwise, return $true.

De volgende code implementeert de Test TargetResource functie.The following code implements the Test-TargetResource function.

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
)

#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 mathes the supplied parameter values. If it does, return true. If it does not, return false.
$result
}

Opmerking: voor gemakkelijker foutopsporing, gebruikt u de Write-Verbose cmdlet in uw implementatie van de vorige drie functies.Note: For easier debugging, use the Write-Verbose cmdlet in your implementation of the previous three functions.

Deze cmdlet schrijft tekst naar de uitgebreide berichtenstroom.This cmdlet writes text to the verbose message stream. Standaard de uitgebreide berichtenstroom niet wordt weergegeven, maar kunt u deze weergeven door het wijzigen van de waarde van de $VerbosePreference variabele of met behulp van de uitgebreid parameter in de DSC-cmdlets = new.By default, the verbose message stream is not displayed, but you can display it by changing the value of the $VerbosePreference variable or by using the Verbose parameter in the DSC cmdlets = new.

Maken van de module-manifestCreating the module manifest

Gebruik tot slot de nieuw ModuleManifest cmdlet voor het definiëren van een .psd1-bestand voor uw aangepaste resource-module.Finally, use the New-ModuleManifest cmdlet to define a .psd1 file for your custom resource module. Als u deze cmdlet aanroept, verwijzen naar het scriptbestand voor module (.psm1) die worden beschreven in de vorige sectie.When you invoke this cmdlet, reference the script module (.psm1) file described in the previous section. Omvatten Get-TargetResource, Set TargetResource, en Test TargetResource in de lijst met functies om te exporteren.Include Get-TargetResource, Set-TargetResource, and Test-TargetResource in the list of functions to export. Hier volgt een voorbeeld-manifestbestand.Following is an example manifest file.

# 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 = ''
}

Ondersteunende PsDscRunAsCredentialSupporting PsDscRunAsCredential

Opmerking: PsDscRunAsCredential wordt ondersteund in PowerShell 5.0 en hoger.Note: PsDscRunAsCredential is supported in PowerShell 5.0 and later.

De PsDscRunAsCredential eigenschap kan worden gebruikt DSC-configuraties resource blok om op te geven dat de resource moet worden uitgevoerd onder een opgegeven set referenties.The PsDscRunAsCredential property can be used in DSC configurations resource block to specify that the resource should be run under a specified set of credentials. Zie voor meer informatie DSC uitgevoerd met gebruikersreferenties.For more information, see Running DSC with user credentials.

Voor toegang tot de gebruikerscontext van binnen een aangepaste bron, kunt u de automatische variabele $PsDscContext.To access the user context from within a custom resource, you can use the automatic variable $PsDscContext.

De volgende code zou bijvoorbeeld de gebruikerscontext waaronder de bron wordt uitgevoerd naar de uitgebreide uitvoerstroom schrijven:For example the following code would write the user context under which the resource is running to the verbose output stream:

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