Scrittura di una risorsa DSC personalizzata con MOFWriting a custom DSC resource with MOF

Si applica a: Windows PowerShell 4.0, Windows PowerShell 5.0Applies To: Windows PowerShell 4.0, Windows PowerShell 5.0

In questo articolo si definirà lo schema per una risorsa personalizzata di Windows PowerShell DSC (Desired State Configuration) in un file MOF e si implementerà la risorsa in un file di script di Windows PowerShell.In this article, 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. Questa risorsa personalizzata consente di creare e gestire un sito Web.This custom resource is for creating and maintaining a web site.

Creazione dello schema MOFCreating the MOF schema

Lo schema definisce le proprietà della risorsa che possono essere configurate da uno script di configurazione DSC.The schema defines the properties of your resource that can be configured by a DSC configuration script.

Struttura di cartelle per una risorsa MOFFolder structure for a MOF resource

Per implementare una risorsa DSC personalizzata con uno schema MOF, creare la struttura di cartelle seguente.To implement a DSC custom resource with a MOF schema, create the following folder structure. Lo schema MOF viene definito nel file Demo_IISWebsite.schema.mof e lo script di risorsa viene definito 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. Facoltativamente, è possibile creare un file manifesto del modulo (con estensione psd1).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)

Nota

È necessario creare una cartella denominata DSCResources nella cartella di primo livello e che la cartella per ogni risorsa abbia lo stesso nome della risorsa.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.

Contenuto del file MOFThe contents of the MOF file

Di seguito è illustrato un esempio di file MOF che è possibile usare per una risorsa di sito Web personalizzata.Following is an example MOF file that can be used for a custom website resource. Per seguire questo esempio, salvare lo schema in un file e denominare il file 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;
};

Si noti quanto segue in relazione al codice precedente:Note the following about the previous code:

  • FriendlyName definisce il nome che è possibile usare per fare riferimento a questa risorsa personalizzata negli script di configurazione DSC.FriendlyName defines the name you can use to refer to this custom resource in DSC configuration scripts. In questo esempio Website equivale al nome descrittivo Archive per la risorsa Archive predefinita.In this example, Website is equivalent to the friendly name Archive for the built-in Archive resource.
  • La classe definita per la risorsa personalizzata deve derivare da OMI_BaseResource.The class you define for your custom resource must derive from OMI_BaseResource.
  • Il qualificatore di tipo, [Key], in una proprietà indica che questa proprietà identificherà in modo univoco l'istanza di risorsa.The type qualifier, [Key], on a property indicates that this property will uniquely identify the resource instance. È obbligatoria almeno una proprietà [Key].At least one [Key] property is required.
  • Il qualificatore [Required] indica che la proprietà è obbligatoria (è necessario specificare un valore in ogni script di configurazione che usa questa risorsa).The [Required] qualifier indicates that the property is required (a value must be specified in any configuration script that uses this resource).
  • Il qualificatore [write] indica che questa proprietà è facoltativa quando si usa la risorsa personalizzata in uno script di configurazione.The [write] qualifier indicates that this property is optional when using the custom resource in a configuration script. Il qualificatore [read] indica che una proprietà non può essere impostata da una configurazione e serve solo a scopo di creazione di report.The [read] qualifier indicates that a property cannot be set by a configuration, and is for reporting purposes only.
  • Values limita i valori che possono essere assegnati alla proprietà all'elenco di valori definiti in ValueMap.Values restricts the values that can be assigned to the property to the list of values defined in ValueMap. Per altre informazioni, vedere l'articolo relativo ai qualificatori ValueMap e Value.For more information, see ValueMap and Value Qualifiers.
  • È consigliabile includere una proprietà denominata Ensure con i valori Present e Absent nella risorsa per mantenere uno stile coerente con le risorse DSC predefinite.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.
  • Assegnare un nome al file di schema per la risorsa personalizzata in base al formato seguente: classname.schema.mof, dove classname è l'identificatore che segue la parola chiave class nella definizione di schema.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.

Scrittura dello script di risorsaWriting the resource script

Lo script di risorsa implementa la logica della risorsa.The resource script implements the logic of the resource. In questo modulo è necessario includere tre funzioni denominate Get-TargetResource, Set-TargetResource e Test-TargetResource.In this module, you must include three functions called Get-TargetResource, Set-TargetResource, and Test-TargetResource. Tutte e tre le funzioni devono accettare un set di parametri identico al set di proprietà definito nello schema MOF creato per la risorsa.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 questo documento il set di proprietà è detto "proprietà della risorsa".In this document, this set of properties is referred to as the "resource properties." Archiviare queste tre funzioni in un file denominato <ResourceName>.psm1.Store these three functions in a file called <ResourceName>.psm1. Nell'esempio seguente le funzioni vengono archiviate in un file denominato Demo_IISWebsite.psm1.In the following example, the functions are stored in a file called Demo_IISWebsite.psm1.

Nota

quando si esegue lo stesso script di configurazione nella risorsa più volte, non devono essere generati errori e la risorsa deve rimanere nello stesso stato impostato quando si esegue lo script una sola volta.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. A tale scopo, verificare che le funzioni Get-TargetResource e Test-TargetResource non modifichino la risorsa e che richiamando la funzione Set-TargetResource più di una volta in una sequenza con gli stessi valori dei parametri si ottenga lo stesso risultato che si ottiene richiamandola una sola volta.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.

Nell'implementazione della funzione Get-TargetResource usare i valori delle proprietà chiave della risorsa forniti come parametri per controllare lo stato dell'istanza di risorsa specificata.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. Questa funzione deve restituire una tabella hash che elenca tutte le proprietà della risorsa come chiavi e i valori effettivi di queste proprietà come valori corrispondenti.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. Il codice seguente fornisce un esempio.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
}

A seconda dei valori specificati per le proprietà della risorsa nello script di configurazione, Set-TargetResource deve eseguire una delle operazioni seguenti:Depending on the values that are specified for the resource properties in the configuration script, the Set-TargetResource must do one of the following:

  • Creare un nuovo sito WebCreate a new website
  • Aggiornare un sito Web esistenteUpdate an existing website
  • Eliminare un sito Web esistenteDelete an existing website

Questa condizione è illustrata nell'esempio seguente.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
    #>
}

Infine, la funzione Test-TargetResource deve accettare lo stesso set di parametri di Get-TargetResource e Set-TargetResource.Finally, the Test-TargetResource function must take the same parameter set as Get-TargetResource and Set-TargetResource. Nell'implementazione di Test-TargetResource controllare lo stato dell'istanza di risorsa specificato nei parametri chiave.In your implementation of Test-TargetResource, check the status of the resource instance that is specified in the key parameters. Se lo stato effettivo dell'istanza di risorsa non corrisponde ai valori specificati nel set di parametri, restituire $false.If the actual status of the resource instance does not match the values specified in the parameter set, return $false. In caso contrario, restituire $true.Otherwise, return $true.

Il codice seguente implementa la funzione Test-TargetResource.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
    )

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

Nota

Per semplificare il debug, usare il cmdlet Write-Verbose nell'implementazione delle tre funzioni precedenti.For easier debugging, use the Write-Verbose cmdlet in your implementation of the previous three functions. Questo cmdlet scrive il testo nel flusso di messaggi dettagliati.This cmdlet writes text to the verbose message stream. Per impostazione predefinita, il flusso di messaggi dettagliati non viene visualizzato, ma è possibile visualizzarlo modificando il valore della variabile $VerbosePreference o usando il parametro Verbose nei cmdlet DSC = 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.

Creazione del manifesto del moduloCreating the module manifest

Usare infine il cmdlet New-ModuleManifest per definire un file <ResourceName>.psd1 per il modulo della risorsa personalizzata.Finally, use the New-ModuleManifest cmdlet to define a <ResourceName>.psd1 file for your custom resource module. Quando si richiama questo cmdlet, fare riferimento al file di modulo di script (con estensione psm1) descritto nella sezione precedente.When you invoke this cmdlet, reference the script module (.psm1) file described in the previous section. Includere Get-TargetResource, Set-TargetResource e Test-TargetResource nell'elenco delle funzioni da esportare.Include Get-TargetResource, Set-TargetResource, and Test-TargetResource in the list of functions to export. Di seguito è riportato un file manifesto di esempio.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 = ''
}

Supporto di PsDscRunAsCredentialSupporting PsDscRunAsCredential

Nota

PsDscRunAsCredential è supportato in PowerShell 5.0 e versioni successive.PsDscRunAsCredential is supported in PowerShell 5.0 and later.

La proprietà PsDscRunAsCredential può essere usata nel blocco di risorsa delle configurazioni DSC per specificare che la risorsa deve essere eseguita in un insieme di credenziali specificato.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. Per altre informazioni, vedere Esecuzione di DSC con le credenziali dell'utente.For more information, see Running DSC with user credentials.

Per accedere al contesto utente dall'interno di una risorsa personalizzata è possibile usare la variabile automatica $PsDscContext.To access the user context from within a custom resource, you can use the automatic variable $PsDscContext.

Ad esempio il codice seguente scrive il contesto utente in cui viene eseguita la risorsa nel flusso di output dettagliato: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";
}

Riavvio del nodoRebooting the Node

Se le azioni eseguite nella funzione Set-TargetResource richiedono un riavvio, è possibile usare il flag globale per indicare alla Gestione configurazione locale di riavviare il nodo.If the actions taken in your Set-TargetResource function require a reboot, you can use a global flag to tell the LCM to reboot the Node. Il riavvio avviene direttamente dopo che la funzione Set-TargetResource è stata completata.This reboot occurs directly after the Set-TargetResource function completes.

All'interno della funzione Set-TargetResource aggiungere la riga di codice seguente.Inside your Set-TargetResource function, add the following line of code.

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

Affinché la Gestione configurazione locale riavvi il nodo, è necessario che il flag RebootNodeIfNeeded sia impostato su $true.In order for the LCM to reboot the Node, the RebootNodeIfNeeded flag needs to be set to $true. È anche necessario che l'opzione ActionAfterReboot sia impostata sul valore predefinito ContinueConfiguration.The ActionAfterReboot setting should also be set to ContinueConfiguration , which is the default. Per altre informazioni sulla configurazione della Gestione configurazione locale, vedere Configurazione di Gestione configurazione locale o Configurazione di Gestione configurazione locale (v4).For more information on configuring the LCM, see Configuring the Local Configuration Manager, or Configuring the Local Configuration Manager (v4).