Escrevendo um recurso personalizado de DSC com MOFWriting a custom DSC resource with MOF

Aplica-se a: Windows PowerShell 4.0, Windows PowerShell 5.0Applies To: Windows PowerShell 4.0, Windows PowerShell 5.0

Neste tópico, definiremos o esquema para um recurso personalizado de Configuração de Estado Desejado (DSC) do Windows PowerShell em um arquivo MOF, além de implementar o recurso em um arquivo de script do Windows PowerShell.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. Esse recurso personalizado serve para criar e manter um site da web.This custom resource is for creating and maintaining a web site.

Criando o esquema MOFCreating the MOF schema

O esquema define as propriedades do recurso que pode ser configurado por um script de configuração DSC.The schema defines the properties of your resource that can be configured by a DSC configuration script.

Estrutura de pastas para um recurso MOFFolder structure for a MOF resource

Para implementar um recurso personalizado de DSC com esquema MOF, crie a seguinte estrutura de pastas.To implement a DSC custom resource with a MOF schema, create the following folder structure. O esquema MOF é definido no arquivo Demo_IISWebsite.schema.mof e o script de recurso é definido no 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. Opcionalmente, você pode criar um arquivo de manifesto do módulo (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)

Observe que é necessário criar uma pasta chamada DSCResources na pasta de nível superior e que a pasta para cada recurso deve ter o mesmo nome que o recurso.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.

O conteúdo do arquivo MOFThe contents of the MOF file

Segue um exemplo de arquivo MOF que pode ser usado para um recurso de sites personalizados.Following is an example MOF file that can be used for a custom website resource. Para seguir esse exemplo, salve o esquema em um arquivo e chame o arquivo de 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;
};

Observe o seguinte sobre o código anterior:Note the following about the previous code:

  • FriendlyName define o nome que você pode usar para se referir a esse recurso personalizado em scripts de configuração DSC.FriendlyName defines the name you can use to refer to this custom resource in DSC configuration scripts. Neste exemplo, Website é equivalente ao nome amigável Archive para o recurso interno Archive.In this example, Website is equivalent to the friendly name Archive for the built-in Archive resource.
  • A classe que você define para o recurso personalizado deve derivar de OMI_BaseResource.The class you define for your custom resource must derive from OMI_BaseResource.
  • O qualificador de tipo, [Key], em uma propriedade indica que essa propriedade identificará exclusivamente a instância do recurso.The type qualifier, [Key], on a property indicates that this property will uniquely identify the resource instance. Pelo menos uma propriedade [Key] é necessária.At least one [Key] property is required.
  • O qualificador [Required] indica que a propriedade é necessária (um valor deve ser especificado em qualquer script de configuração que usa esse recurso).The [Required] qualifier indicates that the property is required (a value must be specified in any configuration script that uses this resource).
  • O qualificador [write] indica que essa propriedade é opcional ao usar o recurso personalizado em um script de configuração.The [write] qualifier indicates that this property is optional when using the custom resource in a configuration script. O qualificador [read] indica que uma propriedade não pode ser definida por uma configuração e destina-se apenas para fins de relatório.The [read] qualifier indicates that a property cannot be set by a configuration, and is for reporting purposes only.
  • Values restringe os valores que podem ser atribuídos à propriedade para a lista de valores definidos em ValueMap.Values restricts the values that can be assigned to the property to the list of values defined in ValueMap. Para obter mais informações, consulte ValueMap e Qualificadores de Valor.For more information, see ValueMap and Value Qualifiers.
  • É recomendável incluir uma propriedade chamada Ensure com os valores Present e Absent em seu recurso como uma maneira de manter um estilo consistente com recursos internos de DSC.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.
  • Nomeie o arquivo de esquema para o recurso personalizado da seguinte maneira: classname.schema.mof, em que classname é o identificador que segue a palavra-chave class na definição do esquema.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.

Escrevendo o script de recursoWriting the resource script

O script de recurso implementa a lógica do recurso.The resource script implements the logic of the resource. Neste módulo, você deve incluir três funções chamadas Get-TargetResource, Set-TargetResource e Test-TargetResource.In this module, you must include three functions called Get-TargetResource, Set-TargetResource, and Test-TargetResource. As três funções precisam usar um conjunto de parâmetros que seja idêntico ao conjunto de propriedades definidas no esquema MOF criado para seu recurso.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. Neste documento, esse conjunto de propriedades é chamado de “propriedades de recursos”.In this document, this set of properties is referred to as the “resource properties.” Armazene essas três funções em um arquivo chamado .psm1.Store these three functions in a file called .psm1. No exemplo a seguir, as funções são armazenadas em um arquivo chamado Demo_IISWebsite.psm1.In the following example, the functions are stored in a file called Demo_IISWebsite.psm1.

Observação: quando você executa o mesmo script de configuração no recurso mais de uma vez, não deve receber erros e o recurso deve permanecer no mesmo estado do script executado uma vez.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. Para fazer isso, verifique se suas funções Get-TargetResource e Test-TargetResource deixam o recurso inalterado e se chamar a função Set-TargetResource mais de uma vez em uma sequência com os mesmos valores de parâmetro é sempre equivalente a chamá-la uma vez.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.

Na implementação da função Get-TargetResource, utilize os valores da propriedade de recurso de chave que são fornecidos como parâmetros para verificar o status da instância do recurso especificado.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. Essa função deve gerar uma tabela de hash que liste todas as propriedades de recursos como chaves e os valores reais dessas propriedades como valores correspondentes.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. O código a seguir fornece um exemplo.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;
}

Dependendo dos valores especificados para as propriedades do recurso no script de configuração, a função Set-TargetResource deve fazer o seguinte:Depending on the values that are specified for the resource properties in the configuration script, the Set-TargetResource must do one of the following:

  • Criar um novo site da webCreate a new website
  • Atualizar um site da web existenteUpdate an existing website
  • Excluir um site da web existenteDelete an existing website

O exemplo a seguir mostra isso.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 #>
}

Por fim, a função Test-TargetResource precisa utilizar o mesmo parâmetro configurado como Get-TargetResource e Set-TargetResource.Finally, the Test-TargetResource function must take the same parameter set as Get-TargetResource and Set-TargetResource. Na implementação de Test-TargetResource, verifique o status da instância do recurso que está especificada nos parâmetros de chave.In your implementation of Test-TargetResource, check the status of the resource instance that is specified in the key parameters. Se o estado real da instância do recurso não coincidir com os valores especificados no conjunto de parâmetros, gere $false.If the actual status of the resource instance does not match the values specified in the parameter set, return $false. Caso contrário, gere $true.Otherwise, return $true.

O código a seguir implementa a função 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
)

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

Observação: para uma depuração mais fácil, use o cmdlet Write-Verbose na implementação das três funções anteriores.Note: For easier debugging, use the Write-Verbose cmdlet in your implementation of the previous three functions.

Esse cmdlet escreve o texto para o fluxo de mensagem detalhada.This cmdlet writes text to the verbose message stream. Por padrão, o fluxo de mensagem detalhada não é exibido, mas você pode exibi-lo alterando o valor da variável $VerbosePreference ou usando o parâmetro Verbose nos cmdlets DSC = novo.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.

Criando o manifesto de móduloCreating the module manifest

Por fim, use o cmdlet New-ModuleManifest para definir um arquivo .psd1 para o módulo de recurso personalizado.Finally, use the New-ModuleManifest cmdlet to define a .psd1 file for your custom resource module. Quando invocar esse cmdlet, faça referência ao arquivo de módulo do script (.psm1) descrito na seção anterior.When you invoke this cmdlet, reference the script module (.psm1) file described in the previous section. Inclua Get-TargetResource, Set-TargetResource e Test-TargetResource na lista de funções para exportar.Include Get-TargetResource, Set-TargetResource, and Test-TargetResource in the list of functions to export. Segue um exemplo de arquivo de manifesto.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 = ''
}

Dando suporte a PsDscRunAsCredentialSupporting PsDscRunAsCredential

Observação: PsDscRunAsCredential tem suporte no PowerShell 5.0 e posterior.Note: PsDscRunAsCredential is supported in PowerShell 5.0 and later.

A propriedade PsDscRunAsCredential pode ser usada no bloco de recurso Configurações DSC para especificar que o recurso deve ser executado em um conjunto de credenciais específico.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. Para obter mais informações, veja Executando o DSC com as credenciais do usuário.For more information, see Running DSC with user credentials.

Para acessar o contexto do usuário de dentro de um recurso personalizado, você pode usar a variável automática $PsDscContext.To access the user context from within a custom resource, you can use the automatic variable $PsDscContext.

Por exemplo, o código a seguir escreveria o contexto do usuário em que o recurso está em execução para o fluxo de saída detalhada: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";
}