Variables et fonctions

Security Controls fournit un jeu de variables et de fonctions PowerShell pour chaque script. Les noms de variable commencent tous par « ST_ ». Les noms de fonction commencent tous par « ST- ». Vous pouvez utiliser ces variables et fonctions dans vos scripts.

Les variables PowerShell peuvent avoir différentes étendues :

Global : Disponible pour la session PowerShell en cours
Script : Déclarée dans le script (hors fonctions) et locale pour ce script
Privé : Déclarée dans une fonction et locale pour cette fonction
Local : Étendue actuelle, qui peut être Global, Script ou Privé

Les variables fournies avec Security Controls sont déclarées dans l'étendue Global. Comme chaque machine cible s'exécute dans sa propre session PowerShell, cela revient à une déclaration dans l'étendue Script.

Variables d'exécution

Le tableau suivant répertorie les variables propres à l'exécution. Toutes les machines voient les mêmes valeurs pour ces variables. Ne modifiez jamais la valeur des variables marquées [Lecture seule].

Nom de variable	Description
ST_OutputDirectory	Chemin complet du répertoire de sortie de base. Un sous-répertoire est créé pour l'exécution concernée. [Lecture seule]
ST_RunDirectory	Chemin complet du répertoire de sortie de l'exécution. [Lecture seule]
ST_RunErrorFile	Chemin complet du fichier d'erreurs de l'exécution. Les erreurs qui ne sont pas propres à une machine donnée doivent être écrites dans ce fichier. Ce fichier contient aussi des messages concernant les machines qui n'ont pas pu être résolues à une adresse IP, et aucun sous-dossier propre à la machine n'est créé pour les machines impossibles à résoudre. [Lecture seule]
ST_RunName	Nom d'exécution spécifié dans l'interface utilisateur lors du lancement ou de la planification de cette exécution ; l'heure d'exécution est ajoutée après ce nom. La valeur par défaut est le nom du script ou du modèle. [Lecture seule]
ST_RunOnConsole	Défini sur $false si le script utilise PowerShell à distance, $true dans le cas contraire. [Lecture seule]
ST_RunOutputFile	Chemin complet du fichier de sortie standard de l'exécution. Toutes les données de sortie qui apparaissent sur la console lors d'une exécution depuis l'invite de commande sont placées dans ce fichier. [Lecture seule]
ST_RunResult	Résultat abrégé de l'exécution, qui apparaît dans Dispositif de surveillance des opérations. Valeur limitée à 100 caractères. Si vous ne définissez pas explicitement cette variable dans votre script, elle est définie de façon à indiquer le nombre de machines ayant connu des erreurs et le nombre d'erreurs de résolution du nom de machine.

Variables de machine

Le tableau suivant répertorie les variables propres à la machine. La valeur de ces variables peut être différente pour chaque machine cible. Vous ne devez jamais modifier la valeur des variables marquées [Lecture seule].

Nom de variable	Description
ST_ComputerName	Nom de l'ordinateur cible. [Lecture seule]
ST_Credential	Objet PSCredential contenant le nom d'utilisateur et le mot de passe SecureString servant à se connecter à la machine cible. Cette variable peut être transmise à toutes les commandes prenant en charge le paramètre Credential (Référence d'authentification). [Lecture seule]
ST_DomainName	Nom du domaine ou du groupe de travail de l'ordinateur cible. [Lecture seule]
ST_MachineDirectory	Chemin complet du répertoire de la machine. En général, il s'agit du nom de la machine. Cependant, si le nom de machine contient des caractères interdits dans les noms de dossier, ces caractères sont remplacés par des caractères Souligné. [Lecture seule]
ST_MachineError	Valeur booléenne qui indique qu'une ou plusieurs erreurs ont été détectées pendant l'exécution du script avec pour cible cette machine spécifique.
ST_MachineErrorFile	Chemin complet du fichier d'erreurs de la machine. Si des erreurs sont détectées pendant l'exécution du script, elles apparaissent dans ce fichier. [Lecture seule]
ST_MachineOutputFile	Chemin complet du fichier de sortie de la machine. La sortie standard générée par le script est capturée dans ce fichier.
ST_MachineResult	Résultat abrégé concernant la machine, qui apparaît dans Dispositif de surveillance des opérations. Valeur limitée à 100 caractères. Si vous ne définissez pas explicitement cette variable dans votre script, elle est définie sur « Success » (Succès) si aucune erreur de machine n'est détectée, ou bien sur le message associé à la première erreur détectée sur cette machine. Utilisez la fonction ST-SetMachineResult pour définir explicitement la valeur de cette variable.
ST_MachineResultSet	Valeur booléenne indiquant que le script a défini la variable ST_MachineResult. Utilisez la fonction ST-SetMachineResult pour définir la variable ST_MachineResult et cette variable-ci.

Fonctions

Security Controls fournit un jeu de fonctions, disponibles pour tous les scripts que vous créez. Vous trouverez leur liste dans le tableau suivant.

Nom de variable	Description
ST-GetTargetOS	Cette fonction tente d'établir une connexion avec le système cible, d'interroger WMI et de récupérer l'objet Win32_OperatingSystem.
ST-SetMachineResult	Cette fonction accepte un paramètre Chaîne. Elle définit la variable ST_MachineResult sur la chaîne transmise et configure ST_MachineResultSet sur $true.
ST-SetMachineError	Cette fonction accepte un argument Chaîne. Elle définit la variable ST_MachineResult sur la chaîne transmise. Elle configure également les variables ST_MachineResultSet et ST_MachineError sur $true.
ST-SendMessage	Cette fonction accepte un paramètre Chaîne. La chaîne s'affiche dans Dispositif de surveillance des opérations. Utilisez cette fonction pour surveiller la progression des scripts dont l'exécution est longue. Une fois le script terminé, la chaîne figurant dans ST_MachineResult apparaît dans Dispositif de surveillance des opérations. À l'exception du débogage, évitez d'appeler cette méthode dans les scripts qui s'exécutent rapidement. La chaîne transmise est tronquée à 100 caractères si elle est plus longue.
ST-CreateMachineDirectory	Normalement, le répertoire de machine n'est pas créé tant qu'aucune sortie n'y est écrite. Si votre script crée des fichiers dans le répertoire de machine, vous devez appeler cette fonction pour créer le répertoire avant d'y écrire des données. Vous pouvez appeler cette fonction plusieurs fois sans problème.
ST-CreateRunDirectory	Normalement, le répertoire d'exécution n'est pas créé tant que l'exécution n'y écrit aucune sortie. Si votre script crée des fichiers dans le répertoire d'exécution, vous devez appeler cette fonction pour créer le répertoire avant d'y écrire des données. Vous pouvez appeler cette fonction plusieurs fois sans problème.
ST-ComputerAndCredential	Cette fonction renvoie les valeurs appropriées à utiliser dans les paramètres ComputerName et Credential pour la machine cible. Pour en savoir plus, reportez-vous à « Spécification des paramètres ComputerName et Credential ».
ST-SubCC	Cette fonction accepte un paramètre Chaîne qui est une commande PowerShell valide. Cette fonction remplace « $ST_CC », dans cette chaîne de commande, par les valeurs correctes à utiliser pour les paramètres ComputerName et Credential dans la commande. Elle exécute ensuite la commande obtenue et renvoie les résultats de l'exécution. Pour en savoir plus, reportez-vous à « Spécification des paramètres ComputerName et Credential ».