Compartilhar via

Recurso de script DSC

  • Artigo

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

O recurso Script na DSC (Configuração de Estado Desejado) 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 definidos para executar as operações de estado DSC correspondentes.

Ponta

Sempre que possível, é prática recomendada usar um recurso de DSC definido em vez deste. O recurso Script 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 recurso de é 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 de forma idempotente ou que ele funcione 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 recurso Script, considere se você pode criar um recurso em vez disso. O uso de recursos de DSC bem definidos torna suas configurações mais legíveis e mantenedíveis.

Nota

Esta documentação deste 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 do PSDscResources.

Sintaxe

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

Nota

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
DependsOn 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.

Nota

A propriedade comum PsDscRunAsCredential foi adicionada ao 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 de o cmdlet Get-DscConfiguration executa para recuperar o estado atual de um nó. Um valor retornado não é necessário de Se você especificar um valor retornado, ele deve ser um hashtable que contém uma chave de resultado cujo valor é uma cadeia de caracteres.

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 booliano. Um resultado de $true indica que o nó está em conformidade e SetScript não deve ser executado.

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

Nota

Toda a saída do TestScript faz parte do valor retornado. 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 dificuldade durante a solução de problemas.

SetScript

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

Exemplos

Exemplo 1: gravar 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 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 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: 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. O caminho local e a versão são configuráveis, desassociando 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 por meio do escopo using. Eles são injetados em cada scriptblock, que usa as variáveis. Os scripts de teste e de definição são removidos para fins 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 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.