Partager via

Ressource de script DSC

  • Article

S’applique à : Windows PowerShell 4.0, Windows PowerShell 5.x

La ressource Script dans Windows PowerShell Desired State Configuration (DSC) fournit un mécanisme permettant d’exécuter des blocs de script Windows PowerShell sur des nœuds cibles. La ressource Script utilise GetScriptSetScriptet TestScript propriétés qui contiennent des blocs de script que vous définissez pour effectuer les opérations d’état DSC correspondantes.

Pourboire

Si possible, il est recommandé d’utiliser une ressource DSC définie au lieu de celle-ci. La ressource Script présente des inconvénients qui rendent plus difficile le test, la maintenance et la prédiction.

Contrairement à d’autres ressources DSC, chaque propriété d’une ressource est une propriété clé et la méthode Get pour cette ressource ne peut retourner qu’une seule chaîne pour l’état actuel. Il n’existe aucune garantie que cette ressource est implémentée de manière idempotente ou qu’elle fonctionnera comme prévu sur n’importe quel système, car elle utilise du code personnalisé. Il ne peut pas être testé sans être appelé sur un système cible.

Avant d’utiliser la ressource Script, déterminez si vous pouvez créer une ressource à la place. L’utilisation de ressources DSC bien définies rend vos configurations plus lisibles et gérables.

Note

Cette documentation de cette ressource DSC couvre la version incluse avec PowerShell antérieure à la version 7.2. Le module PSDscResources contient des ressources DSC nouvelles et mises à jour qui sont officiellement prises en charge par Microsoft. Le module PSDscResources est disponible à partir de PowerShell Gallery.

Pour plus d’informations et la documentation mise à jour, consultez la documentation de référence PSDscResources.

Syntaxe

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

Note

GetScript TestScriptet les blocs SetScript sont stockés sous forme de chaînes.

Propriétés

Propriété Description
GetScript Bloc de script qui retourne l’état actuel du nœud.
SetScript Bloc de script que DSC utilise pour appliquer la conformité lorsque le nœud n’est pas dans l’état souhaité.
TestScript Bloc de script qui détermine si le nœud est dans l’état souhaité.
Credential Indique les informations d’identification à utiliser pour l’exécution de ce script, si des informations d’identification sont requises.

Propriétés communes

Propriété Description
DependsOn Indique que la configuration d’une autre ressource doit s’exécuter avant la configuration de cette ressource.
PsDscRunAsCredential Définit les informations d’identification pour l’exécution de la ressource entière en tant que.

Note

La propriété commune PsDscRunAsCredential a été ajoutée dans WMF 5.0 pour autoriser l’exécution de n’importe quelle ressource DSC dans le contexte d’autres informations d’identification. Pour plus d’informations, consultez Utiliser des informations d’identification avec des ressources DSC.

Informations supplémentaires

GetScript

DSC n’utilise pas la sortie de GetScript l’applet de commande Get-DscConfiguration exécute GetScript pour récupérer l’état actuel d’un nœud. Une valeur de retour n’est pas requise à partir de GetScript Si vous spécifiez une valeur de retour, il doit s’agir d’une table de hachage contenant une clé Result dont la valeur est une chaîne.

TestScript

DSC exécute TestScript pour déterminer si SetScript doit être exécuté. Si TestScript retourne $false, DSC exécute SetScript pour ramener le nœud à l’état souhaité. Elle doit retourner une valeur booléenne. Un résultat de $true indique que le nœud est conforme et SetScript ne doit pas s’exécuter.

L’applet de commande test-DscConfiguration exécute pour récupérer la conformité des nœuds avec les ressources . Toutefois, dans ce cas, SetScript ne s’exécute pas, peu importe ce que TestScript bloc retourne.

Note

Toute la sortie de votre TestScript fait partie de sa valeur de retour. PowerShell interprète la sortie non décompressée comme non nulle, ce qui signifie que votre TestScript retourne $true quel que soit l’état de votre nœud. Cela entraîne des résultats imprévisibles, des faux positifs et provoque des difficultés lors du dépannage.

SetScript

SetScript modifie le nœud pour appliquer l’état souhaité. DSC appelle SetScript si le bloc de script TestScript retourne $false. La SetScript ne doit pas avoir de valeur de retour.

Exemples

Exemple 1 : Écrire un exemple de texte à l’aide d’une ressource de script

Cet exemple teste l’existence de C:\TempFolder\TestFile.txt sur chaque nœud. S’il n’existe pas, il le crée à l’aide de l'SetScript. La GetScript retourne le contenu du fichier et sa valeur de retour n’est pas utilisée.

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

Exemple 2 : Comparer les informations de version à l’aide d’une ressource de script

Cet exemple récupère les informations de version conformes à partir d’un fichier texte sur l’ordinateur de création et les stocke dans la variable $version. Lors de la génération du fichier MOF du nœud, DSC remplace les variables $using:version dans chaque bloc de script par la valeur de la variable $version. Pendant l’exécution, la version conforme est stockée dans un fichier texte sur chaque nœud et comparée et mise à jour lors des exécutions suivantes.

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

Exemple 3 : Utilisation de paramètres dans une ressource de script

Cet exemple accède aux paramètres à partir de la ressource script en utilisant l’étendue using. ConfigurationData sont accessibles de manière similaire. Par exemple 2, l’implémentation s’attend à ce qu’une version soit stockée dans un fichier local sur le nœud cible. Le chemin local et la version sont configurables, découplant le code des données de configuration.

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

Le fichier MOF résultant inclut les variables et leurs valeurs accessibles via l’étendue using. Ils sont injectés dans chaque scriptblock, qui utilise les variables. Les scripts de test et de définition sont supprimés pour la concision :

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

Limitations connues

  • Les informations d’identification transmises dans une ressource de script ne sont pas toujours fiables lors de l’utilisation d’un modèle de serveur pull ou push. Utilisez une ressource complète plutôt que d’utiliser une ressource de script dans ce cas.