Recurso Script de 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 as propriedades GetScriptSetScript e TestScript que contém blocos de script definidos para executar as operações de estado de DSC correspondentes.

Dica

Sempre que possível, é melhor usar um recurso DSC definido em vez deste. O Script recurso tem desvantagens que dificultam o teste, a manutenção e a previsão.

Ao contrário de outros recursos de DSC, cada propriedade de um Script recurso é uma propriedade de 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 ele funcionará conforme o esperado em qualquer sistema, pois ele usa código personalizado. Ele não pode ser testado sem ser invocado em um sistema de destino.

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

Observação

Esta documentação desse recurso DSC aborda a versão incluída no PowerShell antes da versão 7.2. O módulo PSDscResources contém recursos DSC novos e atualizados que têm suporte oficial da 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.

Syntax

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

Observação

GetScriptTestScriptos blocos e SetScript são armazenados como cadeias de caracteres.

Propriedades

Propriedade Descrição
GetScript Um bloco de script que retorna o estado atual do Node.
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 Node está no estado desejado.
Credencial Indica as credenciais que devem ser usadas para executar esse script, caso sejam necessárias.

Propriedades comuns

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

Observação

A propriedade comum PsDscRunAsCredential foi adicionada ao WMF 5.0 para permitir a execução de qualquer recurso de DSC no contexto de outras credenciais. Para saber mais, confira Usar credenciais com recursos de DSC.

Informações adicionais

GetScript

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

TestScript

O DSC é TestScript executado para determinar se SetScript deve ser executado. Se o TestScript retornar $false, o DSC executará o SetScript para colocar o nó de volta no estado desejado. Ele deve retornar um valor booliano. Um resultado de $true indica que o nó está em conformidade e SetScript não deve ser executado.

O cmdlet Test-DscConfiguration é executado TestScript para recuperar a conformidade dos nós com os Script recursos. No entanto, nesse caso, SetScript não é executado, independentemente do TestScript retorno do bloco.

Observação

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

SetScript

SetScript modifica o nó para impor o estado desejado. O DSC chamará SetScript se o TestScript bloco de script retornar $false. O SetScript não deve ter nenhum 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 ele não existir, ele o criará usando o SetScript. O GetScript retorna o conteúdo do arquivo e seu valor retornado 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 da versão compatível de um arquivo de texto no computador de criação e as armazenam na variável $version. 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 é armazenada em um arquivo de texto em cada Node, comparada e atualizada em 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: Utilizar parâmetros em um recurso de script

Este exemplo acessa parâmetros de dentro do recurso de 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. O caminho local e a versão são configuráveis, separando 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 respectivos valores acessados por meio do escopo using. Eles são injetados em cada scriptblock, que usa as variáveis. Os scripts test e set são removidos para 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 passadas em 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 nesse caso.