Partilhar via

Recurso de script DSC

  • Artigo

Aplica-se a: Windows PowerShell 4.0, Windows PowerShell 5.x

O recurso Script na Configuração de Estado Desejado (DSC) do Windows PowerShell fornece um mecanismo para executar blocos de script do Windows PowerShell em nós de destino. O recurso Script usa GetScriptSetScripte TestScript propriedades que contêm blocos de script que você define para executar as operações de estado DSC correspondentes.

Dica

Sempre que possível, é uma prática recomendada usar um recurso DSC definido em vez deste. O recurso Script tem desvantagens que o tornam mais difícil de testar, manter e prever.

Ao contrário de outros recursos DSC, cada propriedade para um recurso Script é uma propriedade chave e o método Get para esse recurso só pode retornar uma única cadeia de caracteres para o estado atual. Não há garantias de que esse recurso seja implementado idempotentemente ou que funcione como esperado em qualquer sistema, pois usa código personalizado. Ele não pode ser testado sem ser invocado em um sistema de destino.

Antes de usar o recurso Script, considere se você pode criar um recurso em vez disso. O uso de recursos DSC bem definidos torna suas configurações mais legíveis e fáceis de manter.

Observação

Esta documentação deste recurso DSC abrange a versão incluída no PowerShell anterior à versão 7.2. O módulo PSDscResources contém recursos DSC novos e atualizados que são oficialmente suportados pela Microsoft. O módulo PSDscResources está disponível na Galeria do PowerShell.

Para obter mais informações e documentação atualizada, consulte a documentação de referência PSDscResources.

Sintaxe

Script [string] #ResourceName
{
    GetScript = [string]
    SetScript = [string]
    TestScript = [string]
    [ Credential = [PSCredential] ]
    [ DependsOn = [string[]] ]
    [ PsDscRunAsCredential = [PSCredential] ]
}

Observação

GetScript TestScripte SetScript blocos são armazenados como cadeias de caracteres.

Propriedades

Propriedade Descrição
GetScript Um bloco de script que retorna o estado atual do nó.
SetScript Um bloco de script que o DSC usa para impor a conformidade quando o Nó não está no estado desejado.
TestScript Um bloco de script que determina se o Nó está no estado desejado.
Credencial Indica as credenciais a serem usadas para executar esse script, se as credenciais forem necessárias.

Propriedades comuns

Propriedade Descrição
DependeDe Indica que a configuração de outro recurso deve ser executada antes que esse recurso seja configurado.
PsDscRunAsCredential Define a credencial para executar todo o recurso como.

Observação

O PsDscRunAsCredential propriedade comum foi adicionado no WMF 5.0 para permitir a execução de qualquer recurso DSC no contexto de outras credenciais. Para obter mais informações, consulte Usar credenciais com recursos DSC.

Informações adicionais

GetScript

O DSC não usa a saída do O cmdlet Get-DscConfiguration do executa para recuperar o estado atual de um nó. Um valor de retorno não é necessário de GetScript Se você especificar um valor de retorno, ele deverá ser uma hashtable contendo uma chave Result cujo valor é uma String.

TestScript

O DSC executa TestScript para determinar se SetScript deve ser executado. Se TestScript retornar $false, o DSC executará SetScript para trazer o nó de volta ao estado desejado. Ele deve retornar um valor booleano. Um resultado de $true indica que o nó é compatível e SetScript não deve ser executado.

O cmdlet Test-DscConfiguration executa TestScript para recuperar a conformidade dos nós com os recursos Script. No entanto, neste caso, SetScript não é executado, não importa o que TestScript bloco retorna.

Observação

Toda a saída do seu TestScript faz parte do seu valor de retorno. O PowerShell interpreta a saída não suprimida como diferente de zero, o que significa que seu TestScript retorna $true independentemente do estado do nó. Isso resulta em resultados imprevisíveis, falsos positivos e causa dificuldade durante a solução de problemas.

SetScript

SetScript modifica o nó para impor o estado desejado. DSC chama SetScript se o bloco de script TestScript retornar $false. O SetScript não deve ter valor de retorno.

Exemplos

Exemplo 1: Escrever texto de exemplo usando um recurso de script

Este exemplo testa a existência de C:\TempFolder\TestFile.txt em cada nó. Se não existir, cria-o usando o SetScript. O GetScript retorna o conteúdo do arquivo e seu valor de retorno não é usado.

Configuration ScriptTest
{
    Import-DscResource -ModuleName 'PSDesiredStateConfiguration'

    Node localhost
    {
        Script ScriptExample
        {
            SetScript = {
                $sw = New-Object System.IO.StreamWriter("C:\TempFolder\TestFile.txt")
                $sw.WriteLine("Some sample string")
                $sw.Close()
            }
            TestScript = { Test-Path "C:\TempFolder\TestFile.txt" }
            GetScript = { @{ Result = (Get-Content C:\TempFolder\TestFile.txt) } }
        }
    }
}

Exemplo 2: Comparar informações de versão usando um recurso de script

Este exemplo recupera as informações de versão compatíveis com de um arquivo de texto no computador de criação e as armazena na variável . Ao gerar o arquivo MOF do nó, o DSC substitui as variáveis $using:version em cada bloco de script pelo valor da variável $version. Durante a execução, a versão compatível com é armazenada em um arquivo de texto em cada nó e comparada e atualizada nas execuções subsequentes.

$version = Get-Content 'version.txt'

Configuration ScriptTest
{
    Import-DscResource -ModuleName 'PSDesiredStateConfiguration'

    Node localhost
    {
        Script UpdateConfigurationVersion
        {
            GetScript = {
                $currentVersion = Get-Content (Join-Path -Path $env:SYSTEMDRIVE -ChildPath 'version.txt')
                return @{ 'Result' = "$currentVersion" }
            }
            TestScript = {
                # Create and invoke a scriptblock using the $GetScript automatic variable, which contains a string representation of the GetScript.
                $state = [scriptblock]::Create($GetScript).Invoke()

                if( $state.Result -eq $using:version )
                {
                    Write-Verbose -Message ('{0} -eq {1}' -f $state.Result,$using:version)
                    return $true
                }
                Write-Verbose -Message ('Version up-to-date: {0}' -f $using:version)
                return $false
            }
            SetScript = {
                $using:version | Set-Content -Path (Join-Path -Path $env:SYSTEMDRIVE -ChildPath 'version.txt')
            }
        }
    }
}

Exemplo 3: Utilizando parâmetros em um recurso de script

Este exemplo acessa parâmetros de dentro do recurso Script usando o escopo using. ConfigurationData pode ser acessado de maneira semelhante. Como o exemplo 2, a implementação espera que uma versão seja armazenada dentro de um arquivo local no nó de destino. Tanto o caminho local quanto a versão são configuráveis, desacoplando o código dos dados de configuração.

Configuration ScriptTest
{
    param
    (
        [Version]
        $Version,

        [string]
        $FilePath
    )

    Import-DscResource -ModuleName 'PSDesiredStateConfiguration'

    Node localhost
    {
        Script UpdateConfigurationVersion
        {
            GetScript = {
                $currentVersion = Get-Content -Path $using:FilePath
                return @{ 'Result' = "$currentVersion" }
            }
            TestScript = {
                # Create and invoke a scriptblock using the $GetScript automatic variable,
                # which contains a string representation of the GetScript.
                $state = [scriptblock]::Create($GetScript).Invoke()

                if( $state['Result'] -eq $using:Version )
                {
                    Write-Verbose -Message ('{0} -eq {1}' -f $state['Result'],$using:version)
                    return $true
                }

                Write-Verbose -Message ('Version up-to-date: {0}' -f $using:version)
                return $false
            }
            SetScript = {
                Set-Content -Path $using:FilePath -Value $using:Version
            }
        }
    }
}

O arquivo MOF resultante inclui as variáveis e seus valores acessados através do escopo using. Eles são injetados em cada scriptblock, que usa as variáveis. Os scripts Test e set são removidos por uma questão de brevidade:

instance of MSFT_ScriptResource as $MSFT_ScriptResource1ref
{
 GetScript = "$FilePath ='C:\\Config.ini'\n\n $currentVersion = Get-Content -Path $FilePath\n return @{ 'Result' = \"$currentVersion\" }\n";
 TestScript = ...;
 SetScript = ...;
};

Limitações conhecidas

  • As credenciais que estão sendo passadas dentro de um recurso de script nem sempre são confiáveis ao usar um modelo de servidor pull ou push. Use um recurso completo em vez de usar um recurso de script neste caso.