Escrevendo um recurso DSC personalizado com classes do PowerShell

Aplica-se a: Windows PowerShell 5.0

Com a introdução de classes do PowerShell no Windows PowerShell 5.0, agora você pode definir um recurso DSC criando uma classe. A classe define o esquema e a implementação do recurso, portanto, não há necessidade de criar um arquivo MOF separado. A estrutura de pastas para um recurso baseado em classe também é mais simples, porque uma pasta DSCResources não é necessária.

Em um recurso DSC baseado em classe, o esquema é definido como propriedades da classe que podem ser modificadas com atributos para especificar o tipo de propriedade. O recurso é implementado pelos métodos Get(), Set()e Test() (equivalente às funções Get-TargetResource, Set-TargetResourcee Test-TargetResource em um recurso de script.

Neste artigo, criaremos um recurso simples chamado NewFile que gerencia um arquivo em um caminho especificado.

Para obter mais informações sobre recursos DSC, consulte Criar recursos personalizados de configuração de estado desejado do Windows PowerShell

Observação

Não há suporte para coleções genéricas em recursos baseados em classe.

Estrutura de pastas para um recurso de classe

Para implementar um recurso personalizado DSC com uma classe PowerShell, crie a seguinte estrutura de pastas. A classe é definida em MyDscResource.psm1 e o manifesto do módulo é definido em MyDscResource.psd1.

$env:ProgramFiles\WindowsPowerShell\Modules (folder)
    |- MyDscResource (folder)
        MyDscResource.psm1
        MyDscResource.psd1

Criar a classe

Use a palavra-chave class para criar uma classe do PowerShell. Para especificar que uma classe é um recurso DSC, use o atributo DscResource(). O nome da classe é o nome do recurso DSC.

[DscResource()]
class NewFile {
}

Declarar propriedades

O esquema de recursos DSC é definido como propriedades da classe. Declaramos três propriedades da seguinte forma.

[DscProperty(Key)]
[string] $path

[DscProperty(Mandatory)]
[ensure] $ensure

[DscProperty()]
[string] $content

[DscProperty(NotConfigurable)]
[MyDscResourceReason[]] $Reasons

Observe que as propriedades são modificadas por atributos. O significado dos atributos é o seguinte:

• DscProperty(Key): A propriedade é necessária. A propriedade é uma chave. Os valores de todas as propriedades marcadas como chaves devem ser combinados para identificar exclusivamente uma instância de recurso em uma configuração.
• DscProperty(Obrigatório): A propriedade é obrigatória.
• DscProperty(NotConfigurable): A propriedade é somente leitura. As propriedades marcadas com esse atributo não podem ser definidas por uma configuração, mas são preenchidas pelo método Get() quando presente.
• DscProperty(): A propriedade é configurável, mas não é necessária.

As propriedades $Path e $SourcePath são ambas cadeias de caracteres. O $CreationTime é uma propriedade DateTime. A propriedade $Ensure é um tipo de enumeração, definido da seguinte forma.

enum Ensure
{
    Absent
    Present
}

Classes de incorporação

Se você quiser incluir um novo tipo com propriedades definidas que você pode usar em seu recurso, basta criar uma classe com tipos de propriedade conforme descrito acima.

class MyDscResourceReason {
    [DscProperty()]
    [string] $Code

    [DscProperty()]
    [string] $Phrase
}

Observação

A classe MyDscResourceReason é declarada aqui com o nome do módulo como um prefixo. Embora você possa dar qualquer nome às classes incorporadas, se dois ou mais módulos definirem uma classe com o mesmo nome e forem usados em uma configuração, o PowerShell gerará uma exceção.

Para evitar exceções causadas por conflitos de nome no DSC, prefixe os nomes de suas classes incorporadas com o nome do módulo. Se o nome da sua classe incorporada já não entrar em conflito, você pode usá-lo sem um prefixo.

Se o seu Recurso DSC foi projetado para uso com o recurso de configuração de máquina do Azure Automanage, sempre prefixe o nome da classe incorporada que você cria para a propriedade Reasons.

Funções públicas e privadas

Você pode criar funções do PowerShell dentro do mesmo arquivo de módulo e usá-las dentro dos métodos do seu recurso de classe DSC. As funções devem ser declaradas como públicas, no entanto, os blocos de script dentro dessas funções públicas podem chamar funções que são privadas. A única diferença é se eles estão listados na propriedade FunctionsToExport do manifesto do módulo.

<#
   Public Functions
#>

function Get-File {
    param(
        [ensure]$ensure,

        [parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]$path,

        [String]$content
    )
    $fileContent        = [MyDscResourceReason]::new()
    $fileContent.code   = 'file:file:content'

    $filePresent        = [MyDscResourceReason]::new()
    $filePresent.code   = 'file:file:path'

    $ensureReturn = 'Absent'

    $fileExists = Test-path $path -ErrorAction SilentlyContinue

    if ($true -eq $fileExists) {
        $filePresent.phrase     = "The file was expected to be: $ensure`nThe file exists at path: $path"

        $existingFileContent    = Get-Content $path -Raw
        if ([string]::IsNullOrEmpty($existingFileContent)) {
            $existingFileContent = ''
        }

        if ($false -eq ([string]::IsNullOrEmpty($content))) {
            $content = $content | ConvertTo-SpecialChars
        }

        $fileContent.phrase     = "The file was expected to contain: $content`nThe file contained: $existingFileContent"

        if ($content -eq $existingFileContent) {
            $ensureReturn = 'Present'
        }
    }
    else {
        $filePresent.phrase     = "The file was expected to be: $ensure`nThe file does not exist at path: $path"
        $path = 'file not found'
    }

    return @{
        ensure  = $ensureReturn
        path    = $path
        content = $existingFileContent
        Reasons = @($filePresent,$fileContent)
    }
}

function Set-File {
    param(
        [ensure]$ensure = "Present",

        [parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]$path,

        [String]$content
    )
    Remove-Item $path -Force -ErrorAction SilentlyContinue
    if ($ensure -eq "Present") {
        New-Item $path -ItemType File -Force
        if ([ValidateNotNullOrEmpty()]$content) {
            $content | ConvertTo-SpecialChars | Set-Content $path -NoNewline -Force
        }
    }
}

function Test-File {
    param(
        [ensure]$ensure = "Present",

        [parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]$path,

        [String]$content
    )
    $test = $false
    $get = Get-File @PSBoundParameters

    if ($get.ensure -eq $ensure) {
        $test = $true
    }
    return $test
}

<#
   Private Functions
#>

function ConvertTo-SpecialChars {
    param(
        [parameter(Mandatory = $true,ValueFromPipeline)]
        [ValidateNotNullOrEmpty()]
        [string]$string
    )
    $specialChars = @{
        '`n' = "`n"
        '\\n' = "`n"
        '`r' = "`r"
        '\\r' = "`r"
        '`t' = "`t"
        '\\t' = "`t"
    }
    foreach ($char in $specialChars.Keys) {
        $string = $string -replace ($char,$specialChars[$char])
    }
    return $string
}

Aplicação dos métodos

Os métodos Get(), Set()e Test() são análogos às funções Get-TargetResource, Set-TargetResourcee Test-TargetResource em um recurso de script.

Como prática recomendada, minimize a quantidade de código dentro da implementação da classe. Em vez disso, mova a maioria do seu código para funções públicas no módulo, que podem ser testadas independentemente.

<#
    This method is equivalent of the Get-TargetResource script function.
    The implementation should use the keys to find appropriate
    resources. This method returns an instance of this class with the
    updated key properties.
#>
[NewFile] Get() {
    $get = Get-File -ensure $this.ensure -path $this.path -content $this.content
    return $get
}

<#
    This method is equivalent of the Set-TargetResource script function.
    It sets the resource to the desired state.
#>
[void] Set() {
    $set = Set-File -ensure $this.ensure -path $this.path -content $this.content
}

<#
    This method is equivalent of the Test-TargetResource script
    function. It should return True or False, showing whether the
    resource is in a desired state.
#>
[bool] Test() {
    $test = Test-File -ensure $this.ensure -path $this.path -content $this.content
    return $test
}

O dossiê completo

Segue-se o ficheiro de classe completo.

enum ensure {
    Absent
    Present
}

<#
    This class is used within the DSC Resource to standardize how data
    is returned about the compliance details of the machine. Note that
    the class name is prefixed with the module name - this helps prevent
    errors raised when multiple modules with DSC Resources define the
    Reasons property for reporting when they're out-of-state.
#>
class MyDscResourceReason {
    [DscProperty()]
    [string] $Code

    [DscProperty()]
    [string] $Phrase
}

<#
   Public Functions
#>

function Get-File {
    param(
        [ensure]$ensure,

        [parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]$path,

        [String]$content
    )
    $fileContent        = [MyDscResourceReason]::new()
    $fileContent.code   = 'file:file:content'

    $filePresent        = [MyDscResourceReason]::new()
    $filePresent.code   = 'file:file:path'

    $ensureReturn = 'Absent'

    $fileExists = Test-path $path -ErrorAction SilentlyContinue

    if ($true -eq $fileExists) {
        $filePresent.phrase     = "The file was expected to be: $ensure`nThe file exists at path: $path"

        $existingFileContent    = Get-Content $path -Raw
        if ([string]::IsNullOrEmpty($existingFileContent)) {
            $existingFileContent = ''
        }

        if ($false -eq ([string]::IsNullOrEmpty($content))) {
            $content = $content | ConvertTo-SpecialChars
        }

        $fileContent.phrase     = "The file was expected to contain: $content`nThe file contained: $existingFileContent"

        if ($content -eq $existingFileContent) {
            $ensureReturn = 'Present'
        }
    }
    else {
        $filePresent.phrase     = "The file was expected to be: $ensure`nThe file does not exist at path: $path"
        $path = 'file not found'
    }

    return @{
        ensure  = $ensureReturn
        path    = $path
        content = $existingFileContent
        Reasons = @($filePresent,$fileContent)
    }
}

function Set-File {
    param(
        [ensure]$ensure = "Present",

        [parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]$path,

        [String]$content
    )
    Remove-Item $path -Force -ErrorAction SilentlyContinue
    if ($ensure -eq "Present") {
        New-Item $path -ItemType File -Force
        if ([ValidateNotNullOrEmpty()]$content) {
            $content | ConvertTo-SpecialChars | Set-Content $path -NoNewline -Force
        }
    }
}

function Test-File {
    param(
        [ensure]$ensure = "Present",

        [parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]$path,

        [String]$content
    )
    $test = $false
    $get = Get-File @PSBoundParameters

    if ($get.ensure -eq $ensure) {
        $test = $true
    }
    return $test
}

<#
   Private Functions
#>

function ConvertTo-SpecialChars {
    param(
        [parameter(Mandatory = $true,ValueFromPipeline)]
        [ValidateNotNullOrEmpty()]
        [string]$string
    )
    $specialChars = @{
        '`n' = "`n"
        '\\n' = "`n"
        '`r' = "`r"
        '\\r' = "`r"
        '`t' = "`t"
        '\\t' = "`t"
    }
    foreach ($char in $specialChars.Keys) {
        $string = $string -replace ($char,$specialChars[$char])
    }
    return $string
}

<#
    This resource manages the file in a specific path.
    [DscResource()] indicates the class is a DSC resource
#>

[DscResource()]
class NewFile {

    <#
        This property is the fully qualified path to the file that is
        expected to be present or absent.

        The [DscProperty(Key)] attribute indicates the property is a
        key and its value uniquely identifies a resource instance.
        Defining this attribute also means the property is required
        and DSC will ensure a value is set before calling the resource.

        A DSC resource must define at least one key property.
    #>
    [DscProperty(Key)]
    [string] $path

    <#
        This property indicates if the settings should be present or absent
        on the system. For present, the resource ensures the file pointed
        to by $Path exists. For absent, it ensures the file point to by
        $Path does not exist.

        The [DscProperty(Mandatory)] attribute indicates the property is
        required and DSC will guarantee it is set.

        If Mandatory is not specified or if it is defined as
        Mandatory=$false, the value is not guaranteed to be set when DSC
        calls the resource.  This is appropriate for optional properties.
    #>
    [DscProperty(Mandatory)]
    [ensure] $ensure

    <#
        This property is optional. When provided, the content of the file
        will be overwridden by this value.
    #>
    [DscProperty()]
    [string] $content

    <#
        This property reports the reasons the machine is or is not compliant.

        [DscProperty(NotConfigurable)] attribute indicates the property is
        not configurable in DSC configuration.  Properties marked this way
        are populated by the Get() method to report additional details
        about the resource when it is present.
    #>
    [DscProperty(NotConfigurable)]
    [MyDscResourceReason[]] $Reasons

    <#
        This method is equivalent of the Get-TargetResource script function.
        The implementation should use the keys to find appropriate
        resources. This method returns an instance of this class with the
        updated key properties.
    #>
    [NewFile] Get() {
        $get = Get-File -ensure $this.ensure -path $this.path -content $this.content
        return $get
    }

    <#
        This method is equivalent of the Set-TargetResource script function.
        It sets the resource to the desired state.
    #>
    [void] Set() {
        $set = Set-File -ensure $this.ensure -path $this.path -content $this.content
    }

    <#
        This method is equivalent of the Test-TargetResource script
        function. It should return True or False, showing whether the
        resource is in a desired state.
    #>
    [bool] Test() {
        $test = Test-File -ensure $this.ensure -path $this.path -content $this.content
        return $test
    }
}

Criar um manifesto

Para disponibilizar um recurso baseado em classe para o mecanismo DSC, você deve incluir uma instrução DscResourcesToExport no arquivo de manifesto que instrui o módulo a exportar o recurso. O nosso manifesto tem o seguinte aspeto:

@{

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

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

    # ID used to uniquely identify this module
    GUID = 'fad0d04e-65d9-4e87-aa17-39de1d008ee4'

    # Author of this module
    Author = 'Microsoft Corporation'

    # Company or vendor of this module
    CompanyName = 'Microsoft Corporation'

    # Copyright statement for this module
    Copyright = ''

    # Description of the functionality provided by this module
    Description = 'Create and set content of a file'

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

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

    # DSC resources to export from this module
    DscResourcesToExport = @('NewFile')

    # Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
    PrivateData = @{

        PSData = @{

            # Tags applied to this module. These help with module discovery in online galleries.
            # Tags = @(Power Plan, Energy, Battery)

            # A URL to the license for this module.
            # LicenseUri = ''

            # A URL to the main website for this project.
            # ProjectUri = ''

            # A URL to an icon representing this module.
            # IconUri = ''

            # ReleaseNotes of this module
            # ReleaseNotes = ''

        } # End of PSData hashtable

    }
}

Testar o recurso

Depois de salvar os arquivos de classe e manifesto na estrutura de pastas, conforme descrito anteriormente, você pode criar uma configuração que use o novo recurso. Para obter informações sobre como executar uma configuração DSC, consulte Enacting configurations. A configuração a seguir verificará se o arquivo em /tmp/test.txt existe e se o conteúdo corresponde à cadeia de caracteres fornecida pela propriedade 'Content'. Se não, todo o arquivo é gravado.

Configuration MyConfig
{
    Import-DSCResource -ModuleName NewFile
    NewFile testFile
    {
        Path = "/tmp/test.txt"
        Content = "DSC Rocks!"
        Ensure = "Present"
    }
}
MyConfig

Suporte PsDscRunAsCredential

[Nota] PsDscRunAsCredential é suportado no PowerShell 5.0 e posterior.

A propriedade PsDscRunAsCredential pode ser usada em configurações DSC bloco de recursos para especificar que o recurso deve ser executado sob um conjunto especificado de credenciais. Para obter mais informações, consulte executando DSC com credenciais de usuário.

Exigir ou não permitir PsDscRunAsCredential para seu recurso

O atributo DscResource() usa um parâmetro opcional RunAsCredential. Este parâmetro usa um dos três valores:

• Optional PsDscRunAsCredential é opcional para configurações que chamam esse recurso. Este é o valor padrão.
• Mandatory PsDscRunAsCredential deve ser usado para qualquer configuração que chame esse recurso.
• NotSupported Configurações que chamam esse recurso não podem usar PsDscRunAsCredential.
• Default O mesmo que Optional.

Por exemplo, use o seguinte atributo para especificar que seu recurso personalizado não oferece suporte ao uso de PsDscRunAsCredential :

[DscResource(RunAsCredential=NotSupported)]
class NewFile {
}

Declarando vários recursos de classe em um módulo

Um módulo pode definir vários recursos DSC baseados em classe. Você só precisa declarar todas as classes no mesmo arquivo .psm1 e incluir cada nome no manifesto .psd1.

$env:ProgramFiles\WindowsPowerShell\Modules (folder)
     |- MyDscResource (folder)
        |- MyDscResource.psm1
           MyDscResource.psd1

Acessar o contexto do usuário

Para acessar o contexto do usuário de dentro de um recurso personalizado, você pode usar a variável automática $global:PsDscContext.

Por exemplo, o código a seguir gravaria o contexto do usuário sob o qual o recurso está sendo executado no fluxo de saída detalhado:

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

Ver também

criar recursos personalizados de configuração de estado desejado do Windows PowerShell