DSC-Ressource „Script“

  • Artikel

Gilt für: Windows PowerShell 4.0, Windows PowerShell 5.x

Die Ressource Script in Windows PowerShell DSC bietet einen Mechanismus zum Anwenden von Windows PowerShell-Skriptblöcken auf Zielknoten. Die Ressource Script verwendet die Eigenschaften GetScriptSetScript und TestScript, die von Ihnen definierte Skriptblöcke enthalten, um die entsprechenden DSC-Zustandsvorgänge auszuführen.

Tipp

Wenn möglich, empfiehlt es sich, anstelle dieser eine definierte DSC-Ressource zu verwenden. Die Script Ressource hat Nachteile, die das Testen, Verwalten und Vorhersagen erschweren.

Im Gegensatz zu anderen DSC-Ressourcen ist jede Eigenschaft für eine Script Ressource eine Schlüsseleigenschaft, und die Get-Methode für diese Ressource kann nur eine einzelne Zeichenfolge für den aktuellen Zustand zurückgeben. Es gibt keine Garantie, dass diese Ressource idempotent implementiert wird oder dass sie auf jedem System wie erwartet funktioniert, da sie benutzerdefinierten Code verwendet. Es kann nicht getestet werden, ohne auf einem Zielsystem aufgerufen zu werden.

Überlegen Sie vor der Verwendung der Script Ressource, ob Sie stattdessen eine Ressource erstellen können. Die Verwendung gut definierter DSC-Ressourcen macht Ihre Konfigurationen lesbarer und verwaltbarer.

Hinweis

Diese Dokumentation dieser DSC-Ressource behandelt die Version, die in PowerShell vor Version 7.2 enthalten ist. Das PSDscResources-Modul enthält neue und aktualisierte DSC-Ressourcen, die offiziell von Microsoft unterstützt werden. Das Modul PSDscResources ist im PowerShell-Katalog verfügbar.

Weitere Informationen und aktualisierte Dokumentation finden Sie in der Referenzdokumentation zu PSDscResources.

Syntax

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

Hinweis

GetScriptTestScript, und SetScript Blöcke werden als Zeichenfolgen gespeichert.

Eigenschaften

Eigenschaft BESCHREIBUNG
GetScript Ein Skriptblock, der den aktuellen Zustand des Knotens zurückgibt.
SetScript Ein Skriptblock, den DSC verwendet, um die Konformität zu erzwingen, wenn sich der Knoten nicht im gewünschten Zustand befindet.
TestScript Ein Skriptblock, der bestimmt, ob der Knoten im gewünschten Zustand ist.
Anmeldeinformationen Gibt die Anmeldeinformationen zum Ausführen dieses Skripts an, falls Anmeldeinformationen erforderlich sind.

Allgemeine Eigenschaften

Eigenschaft BESCHREIBUNG
DependsOn Gibt an, dass die Konfiguration einer anderen Ressource ausgeführt werden muss, bevor diese Ressource konfiguriert wird.
PsDscRunAsCredential Legt die Anmeldeinformationen für die Ausführung der gesamten Ressource fest.

Hinweis

Die allgemeine Eigenschaft PsDscRunAsCredential wurde in WMF 5.0 hinzugefügt, um das Ausführen einer beliebigen DSC-Ressource in Verbindung mit anderen Anmeldeinformationen zu ermöglichen. Weitere Informationen finden Sie unter Use Credentials with DSC Resources (Verwenden von Anmeldeinformationen mit DSC-Ressourcen).

Zusätzliche Informationen

GetScript

DSC verwendet nicht die Ausgabe des GetScript Cmdlets Get-DscConfiguration , das ausgeführt wird GetScript , um den aktuellen Status eines Knotens abzurufen. Ein Rückgabewert ist von nicht erforderlich GetScript Wenn Sie einen Rückgabewert angeben, muss es sich um eine Hashtabelle handeln, die einen Result-Schlüssel enthält, dessen Wert eine Zeichenfolge ist.

TestScript

DSC wird ausgeführt TestScript , um zu bestimmen, ob SetScript ausgeführt werden soll. Wenn TestScript den Wert $false zurückgibt, führt DSC SetScript aus, um den Knoten wieder in den gewünschten Zustand zu versetzen. Es muss ein boolescher Wert zurückgegeben werden. Ein Ergebnis von $true gibt an, dass der Knoten konform ist und SetScript nicht ausgeführt werden soll.

Das Cmdlet Test-DscConfiguration wird ausgeführt, um die Knotenkonformität TestScript mit den Script Ressourcen abzurufen. In diesem Fall wird jedoch nicht ausgeführt, SetScript unabhängig davon, welcher TestScript Block zurückgegeben wird.

Hinweis

Die gesamte Ausgabe von TestScript ist Teil des Rückgabewerts. PowerShell interpretiert die nicht komprimierte Ausgabe als ungleich Null, was bedeutet, dass Ihre TestScript Ausgabe unabhängig vom Status Ihres Knotens zurückgegeben wird $true . Dies führt zu unvorhersehbaren Ergebnissen und zu falsch positiven Ergebnissen und erschwert so die Problembehandlung.

SetScript

SetScript ändert den Knoten, um den gewünschten Zustand zu erzwingen. DSC ruft auf SetScript , wenn der TestScript Skriptblock zurückgibt $false. SetScript sollte keinen Rückgabewert haben.

Beispiele

Beispiel 1: Schreiben von Beispieltext mit einer Skriptressource

Dieses Beispiel testet das Vorhandensein von C:\TempFolder\TestFile.txt auf jedem Knoten. Wenn es nicht vorhanden ist, wird es mithilfe von SetScripterstellt. Gibt GetScript den Inhalt der Datei zurück, und ihr Rückgabewert wird nicht verwendet.

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) } }
        }
    }
}

Beispiel 2: Vergleichen von Versionsinformationen mit einer Skriptressource

Dieses Beispiel ruft die Informationen zur konformen Version aus einer Textdatei auf dem zur Erstellung verwendeten Computer ab und speichert sie in der $version-Variablen. Beim Generieren der MOF-Datei des Knotens ersetzt DSC die $using:version-Variablen in jedem Skriptblock durch den Wert der $version-Variablen. Während der Ausführung wird die konforme Version in einer Textdatei auf jedem Knoten gespeichert und bei nachfolgenden Ausführungen verglichen und aktualisiert.

$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')
            }
        }
    }
}

Beispiel 3: Verwenden von Parametern in einer Skriptressource

In diesem Beispiel wird in der Skriptressource auf Parameter zugegriffen, indem der using-Bereich verwendet wird. Auf ConfigurationData kann auf ähnliche Weise zugegriffen werden. Wie in Beispiel 2 erwartet die Implementierung, dass eine Version in einer lokalen Datei auf dem Zielknoten gespeichert wird. Sowohl der lokale Pfad als auch die Version sind konfigurierbar, was Code von Konfigurationsdaten entkoppelt.

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
            }
        }
    }
}

Die resultierende MOF-Datei enthält die Variablen und deren Werte, auf die über den using-Bereich zugegriffen wird. Sie werden in jeden Skriptblock eingefügt, der die Variablen verwendet. Test- und Setskripts werden aus Gründen der Kürze entfernt:

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 = ...;
};

Bekannte Einschränkungen

  • Anmeldeinformationen, die innerhalb einer Skriptressource übergeben werden, sind bei Verwendung eines Pull- oder Pushservermodells nicht immer zuverlässig. Verwenden Sie in diesem Fall eine vollständige Ressource anstelle einer Skriptressource.