DSC-Skriptressource

Artikel
08/08/2024

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

Die Script-Ressource in der Windows PowerShell Desired State Configuration (DSC) bietet einen Mechanismus zum Ausführen von Windows PowerShell-Skriptblöcken auf Zielknoten. Die Script Ressource verwendet GetScriptSetScriptund TestScript Eigenschaften, die Skriptblöcke enthalten, die Sie zum Ausführen der entsprechenden DSC-Zustandsvorgänge definieren.

Trinkgeld

Wenn möglich, empfiehlt es sich, anstelle dieser ressource eine definierte DSC-Ressource zu verwenden. Die Script Ressource hat Nachteile, die es schwieriger machen, zu testen, zu warten und vorherzusagen.

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 Garantien, dass diese Ressource idempotently implementiert wird oder dass sie auf jedem System wie erwartet funktioniert, da sie benutzerdefinierten Code verwendet. Es kann nicht getestet werden, ohne auf ein Zielsystem aufgerufen zu werden.

Bevor Sie die -Ressource verwenden, überlegen Sie, ob Sie stattdessen eine Ressource können. Durch die Verwendung von gut definierten DSC-Ressourcen können Ihre Konfigurationen besser lesbar und verwaltet werden.

Anmerkung

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 PSDscResources Modul ist im PowerShell-Katalog verfügbar.

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

Syntax

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

Anmerkung

GetScript TestScriptund SetScript Blöcke werden als Zeichenfolgen gespeichert.

Eigenschaften

Eigentum	Beschreibung
GetScript	Ein Skriptblock, der den aktuellen Status des Knotens zurückgibt.
SetScript	Ein Skriptblock, den DSC zum Erzwingen der Compliance verwendet, wenn sich der Knoten nicht im gewünschten Zustand befindet.
TestScript	Ein Skriptblock, der bestimmt, ob sich der Knoten im gewünschten Zustand befindet.
Berechtigungsnachweis	Gibt die Anmeldeinformationen an, die für die Ausführung dieses Skripts verwendet werden sollen, falls Anmeldeinformationen erforderlich sind.

Gemeingüter

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

Anmerkung

Die PsDscRunAsCredential gemeinsame Eigenschaft wurde in WMF 5.0 hinzugefügt, um das Ausführen einer DSC-Ressource im Kontext anderer Anmeldeinformationen zu ermöglichen. Weitere Informationen finden Sie unter Verwenden von Anmeldeinformationen mit DSC Resources.

Zusatzinformation

GetScript

DSC verwendet die Ausgabe aus GetScript Das Get-DscConfiguration-Cmdlet führt Cmdlet GetScript aus, um den aktuellen Zustand eines Knotens abzurufen. Ein Rückgabewert ist aus GetScript Wenn Sie einen Rückgabewert angeben, muss es sich um eine Hashtabelle mit einem Result-Schlüssel, dessen Wert eine Zeichenfolge ist, sein.

TestScript

DSC führt TestScript aus, um festzustellen, ob SetScript ausgeführt werden soll. Wenn TestScript$falsezurückgibt, führt DSC SetScript aus, um den Knoten zurück in den gewünschten Zustand zu bringen. Er muss einen booleschen Wert zurückgeben. Ein Ergebnis von $true gibt an, dass der Knoten kompatibel ist und SetScript nicht ausgeführt werden sollten.

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

Anmerkung

Alle Ausgaben ihrer TestScript sind Teil des Rückgabewerts. PowerShell interpretiert die nicht komprimierte Ausgabe als ungleich Null. Dies bedeutet, dass Ihr TestScript unabhängig vom Status Des Knotens $true zurückgibt. Dies führt zu unvorhersehbaren Ergebnissen, falsch positiven Ergebnissen und verursacht Probleme bei der Problembehandlung.

SetScript

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

Beispiele

Beispiel 1: Schreiben von Beispieltext mithilfe einer Skriptressource

In diesem Beispiel wird das Vorhandensein von C:\TempFolder\TestFile.txt auf jedem Knoten getestet. Wenn sie nicht vorhanden ist, wird sie mithilfe des SetScripterstellt. Die GetScript gibt den Inhalt der Datei zurück, und der 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 mithilfe einer Skriptressource

In diesem Beispiel werden die kompatiblen Versionsinformationen aus einer Textdatei auf dem Erstellungscomputer abgerufen und in der variablen $version gespeichert. 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 kompatible 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 auf Parameter innerhalb der Skriptressource zugegriffen, indem der using Bereich verwendet wird. 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 und entkoppeln Code von Konfigurationsdaten.

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 Scriptblock eingefügt, der die Variablen verwendet. Test- und Set-Skripts werden aus Platzgründen 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, anstatt eine Skriptressource zu verwenden.

Freigeben über

DSC-Skriptressource

Syntax

Eigenschaften

Gemeingüter

Zusatzinformation

GetScript

TestScript

SetScript

Beispiele

Beispiel 1: Schreiben von Beispieltext mithilfe einer Skriptressource

Beispiel 2: Vergleichen von Versionsinformationen mithilfe einer Skriptressource

Beispiel 3: Verwenden von Parametern in einer Skriptressource

Bekannte Einschränkungen

Zusätzliche Ressourcen