about_WorkflowCommonParameters

Article
11/06/2024

DESCRIPTION COURTE

Cette rubrique décrit les paramètres valides sur toutes les commandes de flux de travail Windows PowerShell. Étant donné que le moteur Windows PowerShell les ajoute aux flux de travail, vous pouvez utiliser ces paramètres sur n’importe quel flux de travail et ils sont automatiquement activés sur les flux de travail que vous créez.

DESCRIPTION DÉTAILLÉE

Les paramètres courants windows PowerShell Workflow sont un ensemble de paramètres d’applet de commande que vous pouvez utiliser avec tous les flux de travail et activités Windows PowerShell. Ils sont ajoutés par le moteur de flux de travail Windows PowerShell, et non par l’auteur du flux de travail, et ils sont automatiquement disponibles sur les flux de travail et les activités. Toutefois, les flux de travail imbriqués à trois niveaux approfondis ne prennent pas en charge les paramètres courants, y compris les paramètres communs de flux de travail.

Tous les paramètres de flux de travail sont facultatifs et nommés (et non positionnels). Ils ne prennent pas d’entrée à partir du pipeline.

La plupart des paramètres courants de flux de travail ont un PS préfixe, tel que PSComputerName et PSCredential. Les paramètres avec préfixe PS configurent la connexion et l’environnement d’exécution pour les ordinateurs cibles, également appelés « nœuds distants ».

La plupart des paramètres courants de flux de travail, tels que PSAllowRedirection et AsJob, ont des noms similaires aux paramètres utilisés dans la communication à distance Windows PowerShell et les travaux en arrière-plan. Ces paramètres fonctionnent de la même façon que les paramètres de communication à distance et de travail nommés de la même façon. Vous pouvez donc utiliser les connaissances que vous avez développées dans la communication à distance et les travaux pour gérer les flux de travail.

Les flux de travail sont introduits dans Windows PowerShell 3.0.

DESCRIPTIONS DES PARAMÈTRES

Cette section décrit les paramètres courants du flux de travail.

-AsJob <SwitchParameter>

Exécute le flux de travail en tant que travail de flux de travail. La commande de flux de travail retourne immédiatement un objet qui représente un travail parent. Le travail parent contient les travaux enfants qui s’exécutent sur chacun des ordinateurs cibles. Pour gérer la tâche, utilisez les applets de commande Job. Pour obtenir les résultats du travail, utilisez Receive-Job.

-JobName <String>

Spécifie un nom convivial pour le travail de flux de travail. Par défaut, les travaux sont nommés Job<n>, où <n> est un nombre ordinal.

Si vous utilisez le paramètre JobName dans une commande de flux de travail, le flux de travail est exécuté en tant que travail et la commande de flux de travail retourne un objet de travail, même si vous n’incluez pas le paramètre AsJob dans la commande.

Pour plus d’informations sur les travaux en arrière-plan Windows PowerShell, consultez about_Jobs.

-PSAllowRedirection <SwitchParameter>

Autorise la redirection de la connexion vers les ordinateurs cibles.

Lorsque vous utilisez le paramètre PSConnectionURI , la destination distante peut retourner une instruction pour rediriger vers un AUTRE URI. Par défaut, Windows PowerShell ne redirige pas les connexions, mais vous pouvez utiliser le paramètre PSAllowRedirection pour autoriser la redirection de la connexion vers l’ordinateur cible.

Vous pouvez également limiter le nombre de fois où la connexion est redirigée en définissant la propriété MaximumConnectionRedirectionCount de la $PSSessionOption variable de préférence ou la propriété MaximumConnectionRedirectionCount de la valeur du paramètre PSSessionOption . La valeur par défaut est 5. Pour plus d’informations, consultez la description du paramètre PSSessionOption et de New-PSSessionOption.

-PSApplicationName <, chaîne>

Spécifie le segment de nom d’application de l’URI de connexion utilisé pour se connecter aux ordinateurs cibles. Utilisez ce paramètre pour spécifier le nom de l’application lorsque vous n’utilisez pas le paramètre ConnectionURI dans la commande.

La valeur par défaut est la valeur de la $PSSessionApplicationName variable de préférence sur l’ordinateur local. Si cette variable de préférence n’est pas définie, la valeur par défaut est WSMAN. Cette valeur convient pour la plupart des utilisations. Pour plus d’informations, consultez about_Preference_Variables.

Le service WinRM utilise le nom de l'application pour sélectionner un port d'écoute et traiter la demande de connexion. La valeur de ce paramètre doit correspondre à la valeur de la propriété URLPrefix d’un écouteur sur l’ordinateur distant.

-PSAuthentication <AuthenticationMechanism>

Spécifie le mécanisme utilisé pour authentifier les informations d’identification de l’utilisateur lors de la connexion aux ordinateurs cibles.

Les valeurs valides sont :

Default
Basic
Credssp
Digest
Kerberos
Negotiate
NegotiateWithImplicitCredential

La valeur par défaut est Default.

Pour plus d’informations sur les valeurs de ce paramètre, consultez la description de l’énumération System.Management.Automation.Runspaces.AuthenticationMechanism dans le Kit de développement logiciel (SDK) PowerShell.

Avertissement

L’authentification CredSSP (Credential Security Service Provider), dans laquelle les informations d’identification de l’utilisateur sont transmises à un ordinateur distant à authentifier, est conçue pour les commandes qui nécessitent une authentification sur plusieurs ressources, telles que l’accès à un partage réseau distant. Ce mécanisme augmente le risque de sécurité lié à l'opération distante. Si l'ordinateur distant n'est pas fiable, les informations d'identification qui lui sont passées peuvent être utilisées pour contrôler la session réseau.

-PSAuthenticationLevel <AuthenticationLevel>

Spécifie le niveau d’authentification des connexions aux ordinateurs cibles. La valeur par défaut est Default.

Les valeurs valides sont :

Nom	Description
`Unchanged`	Le niveau d’authentification est identique à la commande précédente.
`Default`	Authentification Windows.
`None`	Aucune authentification COM.
`Connect`	Authentification COM au niveau de la connexion.
`Call`	Authentification COM au niveau de l’appel.
`Packet`	Authentification COM au niveau du paquet.
`PacketIntegrity`	Authentification COM au niveau de l’intégrité des paquets.
`PacketPrivacy`	Authentification COM au niveau de la confidentialité des paquets.

-PSCertificateThumbprint <String>

Spécifie le certificat de clé publique numérique (X509) d'un compte d'utilisateur qui a l'autorisation d'exécuter cette action. Entrez l’empreinte numérique du certificat.

Les certificats sont utilisés dans l'authentification par certificat client. Ils peuvent uniquement être mappés aux comptes d'utilisateurs locaux ; ils ne fonctionnent pas avec les comptes de domaine.

Pour obtenir un certificat, utilisez les applets de commande Get-Item ou Get-ChildItem dans le lecteur Windows PowerShell Cert: .

-PSComputerName <String[]>

Spécifie la liste des ordinateurs qui sont les nœuds cibles du flux de travail. Les commandes ou les activités d’un flux de travail sont exécutées sur les ordinateurs spécifiés à l’aide de ce paramètre. La valeur par défaut est l'ordinateur local.

Tapez le nom NETBIOS, l'adresse IP ou le nom de domaine complet d'un ou de plusieurs ordinateurs dans une liste séparée par des virgules. Pour spécifier l’ordinateur local, tapez le nom de l’ordinateur, localhostou un point (.).

Pour inclure l’ordinateur local dans la valeur du paramètre PSComputerName , ouvrez Windows PowerShell avec l’option Exécuter en tant qu’administrateur .

Si ce paramètre est omis à partir de la commande, ou s’il s’agit $null d’une chaîne vide, la cible de flux de travail est l’ordinateur local et la communication à distance Windows PowerShell n’est pas utilisée pour exécuter la commande.

Pour utiliser une adresse IP dans la valeur du paramètre ComputerName , la commande doit inclure le paramètre PSCredential . En outre, l'ordinateur doit être configuré pour le transport HTTPS ou l'adresse IP de l'ordinateur distant doit être incluse dans la liste TrustedHosts pour WinRM de l'ordinateur local. Pour obtenir des instructions sur l’ajout d’un nom d’ordinateur à la liste TrustedHosts, consultez « How to Add a Computer to the Trusted Host List » dans about_Remote_Troubleshooting.

-PSConfigurationName <, chaîne>

Spécifie les configurations de session utilisées pour configurer des sessions sur les ordinateurs cibles. Entrez une configuration de session sur les ordinateurs cibles (et non sur l’ordinateur serveur de flux de travail). La valeur par défaut est Microsoft.PowerShell.Workflow.

-PSConnectionRetryCount <UInt>

Spécifie le nombre maximal de tentatives de connexion à chaque ordinateur cible si la première tentative de connexion échoue. Entrez un nombre compris entre 1 et 4 294 967 295 (UInt.MaxValue). La valeur par défaut, zéro (0), ne représente aucune tentative de nouvelle tentative.

-PSConnectionRetryIntervalSec <UInt>

Spécifie le délai entre les tentatives de nouvelle tentative de connexion en secondes. La valeur par défaut est zéro (0). Ce paramètre est valide uniquement lorsque la valeur de PSConnectionRetryCount est au moins 1.

-PSConnectionURI <System.Uri>

Spécifie un URI qui définit le point de terminaison de connexion du flux de travail sur l’ordinateur cible. L’URI doit être complet.

Le format de cette chaîne est le suivant :

<Transport>://<ComputerName>:<Port>/<ApplicationName>

La valeur par défaut est http://localhost:5985/WSMAN.

Si vous ne spécifiez pas de PSConnectionURI, vous pouvez utiliser les paramètres PSUseSSL, PSComputerName, PSPort et PSApplicationName pour spécifier les valeurs PSConnectionURI.

Les valeurs valides pour le segment Transport de l’URI sont HTTP et HTTPS. Si vous spécifiez un URI de connexion avec un segment de transport, mais que vous ne spécifiez pas de port, la session est créée avec des ports standards : 80 pour HTTP et 443 pour HTTPS. Pour utiliser les ports par défaut pour la communication à distance Windows PowerShell, spécifiez le port 5985 http ou 5986 https.

-PSCredential <PSCredential>

Spécifie un compte d’utilisateur autorisé à exécuter un flux de travail sur l’ordinateur cible. La valeur par défaut est l’utilisateur actuel. Ce paramètre est valide uniquement lorsque le paramètre PSComputerName est inclus dans la commande.

Tapez un nom d’utilisateur, tel que User01 ou Domain01\User01, ou entrez une variable qui contient un objet PSCredential , tel qu’un objet retourné par l’applet Get-Credential de commande. Si vous entrez uniquement un nom d’utilisateur, vous êtes invité à entrer un mot de passe.

-PSElapsedTimeoutSec <UInt32>

Détermine la durée pendant laquelle le flux de travail et toutes les ressources associées sont conservés dans le système. Lorsque le délai d’expiration expire, le flux de travail est supprimé, même s’il est toujours en cours de traitement. Entrez une valeur comprise entre 10 et 4 294 967 295. La valeur par défaut , 0 (zéro), signifie qu’il n’y a pas de délai d’expiration écoulé.

-PSParameterCollection <Hashtable[]>

Spécifie différentes valeurs de paramètre courantes de flux de travail pour différents ordinateurs cibles.

Entrez une liste séparée par des virgules de tables de hachage avec une table de hachage pour chaque ordinateur cible. Dans chaque table de hachage, la première clé est PSComputerName et sa valeur est le nom de l’ordinateur cible. Les caractères génériques sont autorisés dans le nom de l’ordinateur. Pour les clés restantes dans la table de hachage, la clé est le nom du paramètre et la valeur est la valeur du paramètre.

Par exemple :

-PSParameterCollection @{PSComputerName="*"; PSElapsedTimeoutSec=20},
@{PSComputerName="Server02"},
@{PSComputerName="Server03"},
@{PSComputerName="Server01"; PSElapsedTimeoutSec=10}

Dans l’exemple ci-dessus, toutes les connexions auront un PSElapsedTimeoutSec par défaut de 20 secondes, à l’exception de Server01 qui remplace la valeur par défaut en spécifiant son propre délai d’expiration de 10 secondes.

-PSPersist <Boolean>

Ajoute des points de contrôle au flux de travail, en plus des points de contrôle spécifiés dans le flux de travail.

Ce paramètre ne peut pas supprimer les points de contrôle d’un flux de travail, tels que ceux spécifiés à l’aide du paramètre commun d’activité PSPersist , de l’activité Checkpoint-Workflow ou de la $PSPersistPreference variable.

Un « point de contrôle » ou « point de persistance » est un instantané de l’état du flux de travail et des données capturées pendant l’exécution du flux de travail et enregistré dans un magasin de persistance sur le disque ou dans une base de données SQL. Windows PowerShell Workflow utilise les données enregistrées pour reprendre un flux de travail suspendu ou interrompu à partir du dernier point de persistance, plutôt que de redémarrer le flux de travail.

Valeurs correctes :

(Par défaut) Si vous omettez ce paramètre, un point de contrôle est ajouté au début et à la fin du flux de travail, en plus des points de contrôle spécifiés dans le flux de travail.
$True. Ajoute un point de contrôle au début et à la fin du flux de travail et à un point de contrôle après chaque activité, en plus des points de contrôle spécifiés dans le flux de travail.
$False. Aucun point de contrôle n’est ajouté. Les points de contrôle sont pris uniquement lorsqu’ils sont spécifiés dans le flux de travail.

-PSPort <Int32>

Spécifie le port réseau sur les ordinateurs cibles. Les ports par défaut sont 5985 (le port WinRM pour HTTP) et 5986 (le port WinRM pour HTTPS).

N’utilisez pas le paramètre PSPort , sauf si vous devez. Le port défini dans la commande s’applique à tous les ordinateurs ou sessions sur lesquels la commande s’exécute. Un autre paramètre de port peut empêcher la commande de s'exécuter sur tous les ordinateurs. Avant d'utiliser un autre port, vous devez configurer l'écouteur WinRM sur l'ordinateur distant pour qu'il écoute sur ce port.

-PSPrivateMetadata <Hashtable>

Fournit des informations personnalisées pour les travaux de flux de travail. Entrez une table de hachage. Les clés et les valeurs sont personnalisées pour chaque flux de travail. Pour plus d’informations sur les métadonnées privées d’un flux de travail, consultez la rubrique d’aide du flux de travail.

Ce paramètre n’est pas traité par le moteur de flux de travail Windows PowerShell. Au lieu de cela, le moteur transmet la table de hachage directement au flux de travail.

-PSRunningTimeoutSec <UInt32>

Spécifie l’heure d’exécution du flux de travail en secondes, à l’exclusion de tout moment où le flux de travail est suspendu. Si l’exécution du flux de travail n’est pas terminée lorsque l’heure expire, le moteur de flux de travail Windows PowerShell arrête de force l’exécution du flux de travail.

-PSSessionOption <PSSessionOption>

Définit les options avancées pour les sessions sur les ordinateurs cibles. Entrez un objet PSSessionOption , tel qu’un objet que vous créez à l’aide de l’applet New-PSSessionOption de commande.

Les valeurs par défaut des options de session sont déterminées par la valeur de la $PSSessionOption variable de préférence, si elle est définie. Sinon, la session utilise les valeurs spécifiées dans la configuration de session.

Pour obtenir une description des options de session, y compris les valeurs par défaut, consultez new-PSSessionOption. Pour plus d’informations sur la $PSSessionOption variable de préférence, consultez about_Preference_Variables.

-PSUseSSL <SwitchParameter>

Utilise le protocole SSL (Secure Sockets Layer) pour établir une connexion à l’ordinateur cible. Par défaut, SSL n'est pas utilisé.

WS-Management chiffre tout le contenu Windows PowerShell transmis sur le réseau. UseSSL est une protection supplémentaire qui envoie les données sur un protocole HTTPS, au lieu de HTTP. Si vous utilisez ce paramètre, mais que SSL n'est pas disponible sur le port utilisé pour la commande, celle-ci échoue.

Partager via