Partilhar via

Escrever um recurso DSC personalizado com o MOF

  • Artigo

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

Neste artigo, vamos definir o esquema de um recurso personalizado de Windows PowerShell Desired State Configuration (DSC) num ficheiro MOF e implementar o recurso num ficheiro de script Windows PowerShell. Este recurso personalizado destina-se a criar e manter um web site.

Criar o esquema MOF

O esquema define as propriedades do recurso que podem ser configuradas por um script de configuração do DSC.

Estrutura de pastas para um recurso MOF

Para implementar um recurso personalizado do DSC com um esquema MOF, crie a seguinte estrutura de pastas. O esquema MOF é definido no ficheiro Demo_IISWebsite.schema.mofe o script de recurso é definido em Demo_IISWebsite.psm1. Opcionalmente, pode criar um ficheiro de manifesto de módulo (psd1).

$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)

Nota

É necessário criar uma pasta com o nome DSCResources na pasta de nível superior e que a pasta para cada recurso tem de ter o mesmo nome que o recurso.

O conteúdo do ficheiro MOF

Segue-se um ficheiro MOF de exemplo que pode ser utilizado para um recurso de site personalizado. Para seguir este exemplo, guarde este esquema num ficheiro e chame o ficheiro 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;
};

Tenha em atenção o seguinte sobre o código anterior:

  • FriendlyName define o nome que pode utilizar para fazer referência a este recurso personalizado em scripts de configuração do DSC. Neste exemplo, Website é equivalente ao nome Archive amigável do recurso de Arquivo incorporado.
  • A classe que definir para o recurso personalizado tem de derivar de OMI_BaseResource.
  • O qualificador de tipo, [Key], numa propriedade indica que esta propriedade identificará exclusivamente a instância de recurso. É necessária, pelo menos, uma [Key] propriedade.
  • O [Required] qualificador indica que a propriedade é necessária (tem de ser especificado um valor em qualquer script de configuração que utilize este recurso).
  • O [write] qualificador indica que esta propriedade é opcional ao utilizar o recurso personalizado num script de configuração. O [read] qualificador indica que uma propriedade não pode ser definida por uma configuração e destina-se apenas a relatórios.
  • Values restringe os valores que podem ser atribuídos à propriedade à lista de valores definidos em ValueMap. Para obter mais informações, veja ValueMap e Qualificadores de Valor.
  • A inclusão de uma propriedade chamada Ensure com valores Present e Absent no recurso é recomendada como forma de manter um estilo consistente com recursos DSC incorporados.
  • Atribua o nome ao ficheiro de esquema do recurso personalizado da seguinte forma: classname.schema.mof, em classname que é o identificador que segue a class palavra-chave na definição do esquema.

Escrever o script de recursos

O script de recurso implementa a lógica do recurso. Neste módulo, tem de incluir três funções chamadas Get-TargetResource, Set-TargetResourcee Test-TargetResource. As três funções têm de ter um conjunto de parâmetros idêntico ao conjunto de propriedades definido no esquema MOF que criou para o recurso. Neste documento, este conjunto de propriedades é referido como as "propriedades do recurso". Armazene estas três funções num ficheiro chamado <ResourceName>.psm1. No exemplo seguinte, as funções são armazenadas num ficheiro chamado Demo_IISWebsite.psm1.

Nota

Quando executar o mesmo script de configuração no recurso mais do que uma vez, não deverá receber erros e o recurso deve permanecer no mesmo estado que executar o script uma vez. Para tal, certifique-se de que as funções Get-TargetResource e Test-TargetResource deixam o recurso inalterado e que invocar a Set-TargetResource função mais do que uma vez numa sequência com os mesmos valores de parâmetro é sempre equivalente a invocá-lo uma vez.

Na implementação da Get-TargetResource função, utilize os valores de propriedade do recurso chave que são fornecidos como parâmetros para verificar o estado da instância de recurso especificada. Esta função tem de devolver uma tabela hash que lista todas as propriedades do recurso como chaves e os valores reais destas propriedades como os valores correspondentes. O código seguinte fornece um exemplo.

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

Consoante os valores especificados para as propriedades do recurso no script de configuração, o Set-TargetResource tem de efetuar um dos seguintes procedimentos:

  • Criar um novo site
  • Atualizar um site existente
  • Eliminar um site existente

O exemplo seguinte ilustra isto.

# 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 Test-TargetResource função tem de ter o mesmo parâmetro definido como Get-TargetResource e Set-TargetResource. Na implementação do Test-TargetResource, verifique o estado da instância de recurso especificado nos parâmetros principais. Se o estado real da instância de recurso não corresponder aos valores especificados no conjunto de parâmetros, devolva $false. Caso contrário, devolva $true.

O código seguinte implementa a Test-TargetResource função .

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

Para facilitar a depuração, utilize o Write-Verbose cmdlet na implementação das três funções anteriores. Este cmdlet escreve texto no fluxo de mensagens verbosa. Por predefinição, o fluxo de mensagens verbosa não é apresentado, mas pode apresentá-lo alterando o valor da variável $VerbosePreference ou utilizando o parâmetro Verboso nos cmdlets DSC = novo.

Criar o manifesto do módulo

Por fim, utilize o New-ModuleManifest cmdlet para definir um <ResourceName>.psd1 ficheiro para o módulo de recurso personalizado. Quando invocar este cmdlet, faça referência ao ficheiro do módulo de script (.psm1) descrito na secção anterior. Inclua Get-TargetResource, Set-TargetResourcee Test-TargetResource na lista de funções a exportar. Segue-se um ficheiro de manifesto de exemplo.

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

Suporte PsDscRunAsCredential

Nota

O PsDscRunAsCredential é suportado no PowerShell 5.0 e posterior.

A propriedade PsDscRunAsCredential pode ser utilizada no bloco de recursos de configurações do DSC para especificar que o recurso deve ser executado sob um conjunto especificado de credenciais. Para obter mais informações, veja Executar o DSC com credenciais de utilizador.

Para aceder ao contexto de utilizador a partir de um recurso personalizado, pode utilizar a variável $PsDscContextautomática .

Por exemplo, o código seguinte escreveria o contexto de utilizador no qual o recurso está a ser executado para o fluxo de saída verboso:

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

Reiniciar o Nó

Se as ações executadas na sua Set-TargetResource função exigirem um reinício, pode utilizar um sinalizador global para indicar ao LCM para reiniciar o Nó. Este reinício ocorre logo após a conclusão da Set-TargetResource função.

Dentro da sua Set-TargetResource função, adicione a seguinte linha de código.

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

Para que o LCM reinicie o Nó, o sinalizador RebootNodeIfNeeded tem de ser definido como $true. A definição ActionAfterReboot também deve ser definida como ContinueConfiguration, que é a predefinição. Para obter mais informações sobre como configurar o LCM, veja Configurar a Configuration Manager Local ou Configurar a Configuration Manager Local (v4).