Recurso Script de DSCDSC Script Resource

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

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.The Script resource in Windows PowerShell Desired State Configuration (DSC) provides a mechanism to run Windows PowerShell script blocks on target nodes. O recurso Script tem as propriedades GetScript, SetScript e TestScript.The Script resource has GetScript, SetScript, and TestScript properties. Essas propriedades devem ser definidas em blocos de script que serão executado em cada nó de destino.These properties should be set to script blocks that will run on each target node.

O bloco de script GetScript deve retornar uma tabela de hash que representa o estado do nó atual.The GetScript script block should return a hashtable representing the state of the current node. A tabela de hash deve conter somente uma chave Result e o valor deve ser do tipo String.The hashtable must only contain one key Result and the value must be of type String. Ele não precisa retornar nada.It is not required to return anything. O DSC não faz nada com a saída desse bloco de script.DSC doesn't do anything with the output of this script block.

O bloco de script TestScript deve determinar se o nó atual precisa ser modificado.The TestScript script block should determine if the current node needs to be modified. Ele deverá retornar $true se o nó for atualizado.It should return $true if the node is up-to-date. Ele deverá retornar $false se a configuração do nó estiver desatualizada e deverá ser atualizada pelo bloco de script SetScript.It should return $false if the node's configuration is out-of-date and should be updated by the SetScript script block. O bloco de script TestScript é chamado pelo DSC.The TestScript script block is called by DSC.

O bloco de script SetScript deve modificar o nó.The SetScript script block should modify the node. Ele será chamado pelo DSC, se o bloco TestScript retornar $false.It is called by DSC if the TestScript block return $false.

Se você precisa usar variáveis do seu script de configuração nos blocos de script GetScript, TestScript ou SetScript, use o escopo $using: (consulte abaixo para obter um exemplo).If you need to use variables from your configuration script in the GetScript, TestScript, or SetScript script blocks, use the $using: scope (see below for an example).

SintaxeSyntax

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

PropriedadesProperties

PropriedadeProperty DescriçãoDescription
GetScriptGetScript Fornece um bloco de script do Windows PowerShell que é executado quando você invoca o cmdlet Get-DscConfiguration.Provides a block of Windows PowerShell script that runs when you invoke the Get-DscConfiguration cmdlet. Esse bloco deve retornar uma tabela de hash.This block must return a hashtable. A tabela de hash deve conter somente uma chave Resultado e o valor deve ser do tipo cadeia de caracteres.The hashtable must only contain one key Result and the value must be of type String.
SetScriptSetScript Fornece um bloco de script do Windows PowerShell.Provides a block of Windows PowerShell script. Quando você invoca o cmdlet Start-DscConfiguration, o bloco TestScript é executado primeiro.When you invoke the Start-DscConfiguration cmdlet, the TestScript block runs first. Se o bloco TestScript gerar $false, o bloco SetScript será executado.If the TestScript block returns $false, the SetScript block will run. Se o bloco TestScript gerar $true, o bloco SetScript não será executado.If the TestScript block returns $true, the SetScript block will not run.
TestScriptTestScript Fornece um bloco de script do Windows PowerShell.Provides a block of Windows PowerShell script. Quando você invoca o cmdlet Start-DscConfiguration, esse bloco é executado.When you invoke the Start-DscConfiguration cmdlet, this block runs. Se gerar $false, o bloco SetScript será executado.If it returns $false, the SetScript block will run. Se gerar $true, o bloco SetScript não será executado.If it returns $true, the SetScript block will not run. O bloco TestScript também é executado quando você invoca o cmdlet Test-DscConfiguration.The TestScript block also runs when you invoke the Test-DscConfiguration cmdlet. No entanto, nesse caso, o bloco SetScript não será executado, independentemente do valor gerado pelo bloco TestScript.However, in this case, the SetScript block will not run, no matter what value the TestScript block returns. O bloco TestScript precisará gerar True se a configuração real corresponder à configuração atual de estado desejado e False se não corresponder.The TestScript block must return True if the actual configuration matches the current desired state configuration, and False if it does not match. (A configuração atual de estado desejado é a última configuração aplicada no nó que está usando a DSC.)(The current desired state configuration is the last configuration enacted on the node that is using DSC.)
CredentialCredential Indica as credenciais que devem ser usadas para executar esse script, caso sejam necessárias.Indicates the credentials to use for running this script, if credentials are required.
DependsOnDependsOn Indica que a configuração de outro recurso deve ser executada antes de ele ser configurado.Indicates that the configuration of another resource must run before this resource is configured. Por exemplo, se a ID do bloco de script de configuração do recurso que você deseja executar primeiro for ResourceName e seu tipo for ResourceType, a sintaxe para usar essa propriedade será DependsOn = "[ResourceType]ResourceName".For example, if the ID of the resource configuration script block that you want to run first is ResourceName and its type is ResourceType, the syntax for using this property is DependsOn = "[ResourceType]ResourceName".

Exemplo 1Example 1

$version = Get-Content 'version.txt'

Configuration ScriptTest
{
    Import-DscResource –ModuleName 'PSDesiredStateConfiguration'

    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 2Example 2

$version = Get-Content 'version.txt'

Configuration ScriptTest
{
    Import-DscResource –ModuleName 'PSDesiredStateConfiguration'

    Script UpdateConfigurationVersion
    {
        GetScript = { 
            $currentVersion = Get-Content (Join-Path -Path $env:SYSTEMDRIVE -ChildPath 'version.txt')
            return @{ 'Version' = "$currentVersion" }
        }          
        TestScript = { 
            $state = $GetScript
            if( $state['Version'] -eq $using:version )
            {
                Write-Verbose -Message ('{0} -eq {1}' -f $state['Version'],$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')
        }
    }
}

Este recurso está gravando a versão da configuração em um arquivo de texto.This resource is writing the configuration's version to a text file. Esta versão está disponível no computador cliente, mas não está em nenhum dos nós, por isso deve ser passada para cada um dos blocos de script do recurso Script com o escopo using do PowerShell.This version is available on the client computer, but isn't on any of the nodes, so it has to be passed to each of the Script resource's script blocks with PowerShell's using scope. Quando gera o arquivo MOF do nó, o valor da variável $version é lido de um arquivo de texto no computador cliente.When generating the node's MOF file, the value of the $version variable is read from a text file on the client computer. O DSC substitui as variáveis $using:version em cada bloco de script pelo valor da variável $version.DSC replaces the $using:version variables in each script block with the value of the $version variable.