WorkflowCommonParameters について

概要

このトピックでは、すべての Windows PowerShell ワークフローコマンドで有効なパラメーターについて説明します。 Windows PowerShell エンジンによってワークフローに追加されるため、これらのパラメーターは任意のワークフローで使用でき、作成したワークフローで自動的に有効になります。

詳細説明

Windows PowerShell ワークフローの共通パラメーターは、すべての Windows PowerShell ワークフローとアクティビティで使用できる一連のコマンドレットパラメーターです。これらは、ワークフロー作成者ではなく Windows PowerShell ワークフローエンジンによって追加され、ワークフローとアクティビティで自動的に使用できます。ただし、入れ子になった 3 つのレベルの深いワークフローでは、ワークフローの共通パラメーターを含む一般的なパラメーターはサポートされません。

すべてのワークフローパラメーターは省略可能であり、名前は付けられます (位置指定ではありません)。パイプラインからの入力は受け取りません。

ワークフローの共通パラメーターのほとんどには、 PSComputerName や PSCredential などの PS プレフィックスが付いています。 PS プレフィックス付きパラメーターは、ターゲットコンピューター ("リモートノード" とも呼ばれます) の接続と実行環境を構成します。

PSAllowRedirection や AsJob などのワークフローの一般的なパラメーターの多くは、Windows PowerShell リモート処理ジョブやバックグラウンドジョブで使用されるパラメーターに似た名前が付けられています。これらのパラメーターは、同様の名前のリモート処理およびジョブパラメーターと同じように動作するため、リモート処理とジョブで開発した知識を使用してワークフローを管理できます。

ワークフローは Windows PowerShell 3.0 で導入されています。

パラメーターの説明

このセクションでは、ワークフローの一般的なパラメーターについて説明します。

-AsJob (ジョブとして) <SwitchParameter>

ワークフローをワークフロージョブとして実行します。ワークフローコマンドは、親ジョブを表すオブジェクトを直ちに返します。親ジョブには、各ターゲットコンピューターで実行されている子ジョブが含まれています。ジョブを管理するには、Job コマンドレットを使用します。ジョブの結果を取得するには、 Receive-Job を使用します。

-JobName <文字列>

ワークフロージョブのフレンドリ名を指定します。デフォルトでは、ジョブの名前は "Job<n>" で、 <n> は序数です。

ワークフローコマンドで JobName パラメーターを使用すると、ワークフローはジョブとして実行され、コマンドに Job AsJob パラメーターを含めなくても、ワークフローコマンドはジョブオブジェクトを返します。

Windows PowerShell バックグラウンドジョブの詳細については、「 about_Jobs」を参照してください。

-PSAllowRedirection <SwitchParameter>

ターゲットコンピューターへの接続のリダイレクトを許可します。

PSConnectionURI パラメータを使用すると、リモートの宛先は別の URI にリダイレクトする命令を返すことができます。既定では、Windows PowerShell は接続をリダイレクトしませんが、 PSAllowRedirection パラメーターを使用して、ターゲットコンピューターへの接続のリダイレクトを許可できます。

また、MaximumConnectionRedirectionCount プリファレンス変数の $PSSessionOption プロパティ、または MaximumConnectionRedirectionCount の値の PSSessionOption parameter プロパティを設定することで、接続がリダイレクトされる回数を制限することもできます。既定値は 5 です。詳細については、 PSSessionOption パラメーターと New-PSSessionOption の説明を参照してください。

-PSApplicationName <文字列>

ターゲットコンピューターへの接続に使用される接続 URI のアプリケーション名セグメントを指定します。このパラメーターは、コマンドで ConnectionURI パラメーターを使用しない場合にアプリケーション名を指定するときに使用します。

既定値は、ローカルコンピューターの $PSSessionApplicationName 基本設定変数の値です。このユーザー設定変数が定義されていない場合、既定値は WSMAN です。この値は、ほとんどの用途に適しています。詳細については、about_Preference_Variablesを参照してください。

WinRM サービスでは、アプリケーション名を使用して、接続要求をサービスするリスナーを選択します。このパラメーターの値は、リモートコンピューター上のリスナーの URLPrefix プロパティの値と一致する必要があります。

-PSAuthentication <AuthenticationMechanism>

ターゲットコンピューターに接続するときにユーザーの資格情報を認証するために使用されるメカニズムを指定します。

有効な値は次のとおりです。

デフォルト
基本的な
クレドスプ
ダイジェスト
ケルベロス
ネゴシエイト
NegotiateWithImplicitCredential (英語)

既定値は Defaultです。

このパラメータの値については、MSDN の System.Management.Automation.Runspaces.AuthenticationMechanism 列挙体の説明を参照してください。

Warnung

ユーザーの資格情報が認証されるリモートコンピューターにユーザーの資格情報が渡される資格情報セキュリティサービスプロバイダー (CredSSP) 認証は、リモートネットワーク共有へのアクセスなど、複数のリソースで認証を必要とするコマンド用に設計されています。このメカニズムにより、リモート操作のセキュリティリスクが高まります。リモートコンピューターが侵害された場合、それに渡される資格情報を使用してネットワークセッションを制御できます。

-PSAuthenticationLevel <AuthenticationLevel>

ターゲットコンピューターへの接続の認証レベルを指定します。既定値は Defaultです。

有効な値は次のとおりです。

名前	説明
変更なし	認証レベルは、前のコマンドと同じです。
デフォルト	Windows 認証
なし	COM 認証なし。
接続	接続レベルの COM 認証。
呼び出し	呼び出しレベルの COM 認証。
パケット	パケットレベルの COM 認証。
パケット整合性	パケット整合性レベルの COM 認証。
パケットプライバシー	パケットプライバシーレベルの COM 認証。

-PSCertificateThumbprint <文字列>

このアクションを実行するアクセス許可を持つユーザーアカウントのデジタル公開キー証明書 (X509) を指定します。証明書の拇印を入力します。

証明書は、クライアント証明書ベースの認証で使用されます。これらの証明書は、ローカルユーザーアカウントにしかマップできません。ドメインアカウントでは機能しません。

証明書を取得するには、Windows PowerShell Cert: ドライブの Get-Item または [Get-ChildItem] (xref:Microsoft.PowerShell.Management.Get-Childitem) コマンドレットを使用します。

-PSComputerName <文字列[]>

ワークフローのターゲットノードであるコンピューターの一覧を指定します。ワークフロー内のコマンドまたはアクティビティは、このパラメーターを使用して指定されたコンピューター上で実行されます。既定値はローカルコンピューターです。

1 台または複数のコンピューターの NETBIOS 名、IP アドレス、または完全修飾ドメイン名をコンマ区切りリストで入力します。ローカルコンピューターを指定するには、コンピューター名、"localhost"、またはドット (.) を入力します。

PSComputerName パラメーターの値にローカルコンピューターを含めるには、Windows PowerShell を [管理者として実行] オプションで開きます。

このパラメーターをコマンドから省略するか、値が $null または空の文字列である場合、ワークフローターゲットはローカルコンピューターであり、Windows PowerShell リモート処理はコマンドの実行に使用されません。

ComputerName パラメーターの値に IP アドレスを使用するには、コマンドに PSCredential パラメーターを含める必要があります。また、HTTPS トランスポート用にコンピューターを構成するか、リモートコンピューターの IP アドレスをローカルコンピューターの WinRM TrustedHosts リストに含める必要があります。 TrustedHosts リストにコンピュータ名を追加する手順については、about_Remote_Troubleshooting の「コンピュータを信頼されたホストの一覧に追加する方法」を参照してください。

-PSConfigurationName <文字列>

ターゲットコンピューターでセッションを構成するために使用するセッション構成を指定します。 (ワークフローサーバーコンピューターではなく) ターゲットコンピューターでセッション構成を入力します。既定値は Microsoft.PowerShell.Workflowです。

-PSConnectionRetryCount <UInt>

最初の接続試行が失敗した場合に、各ターゲットコンピューターへの接続試行の最大数を指定します。 1 から 4,294,967,295 までの数値 (UInt.MaxValue) を入力します。デフォルト値のゼロ (0) は、再試行が試行されないことを表します。

-PSConnectionRetryIntervalSec <UInt>

接続再試行の間隔を秒単位で指定します。既定値は 0 です。このパラメーターは、PSConnectionRetryCount の値が 1 以上の場合にのみ有効です。

-PSConnectionURI <System.Uri>

ターゲットコンピューター上のワークフローの接続エンドポイントを定義する URI (Uniform Resource Identifier) を指定します。 URI は完全修飾されている必要があります。

この文字列の形式は次のとおりです。

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

既定値は https://localhost:5985/WSMAN です。

PSConnectionURIを指定しない場合は、PSUseSSL、PSComputerName、PSPort、および PSApplicationName パラメーターを使用してPSConnectionURI値を指定できます。

URI のトランスポートセグメントの有効な値は、 HTTP と HTTPS です。トランスポート・セグメントで接続 URI を指定し、ポートを指定しない場合、セッションは標準ポート (HTTP の場合は 80、HTTPS の場合は 443) で作成されます。 Windows PowerShell リモート処理の既定のポートを使用するには、HTTP の場合はポート 5985、HTTPS の場合は 5986 を指定します。

-PSCredential <PSCredential>

ターゲットコンピューターでワークフローを実行するアクセス許可を持つユーザーアカウントを指定します。既定値は現在のユーザーです。このパラメーターは、コマンドに PSComputerName パラメーターが含まれている場合にのみ有効です。

"User01" や "Domain01\User01" などのユーザー名を入力するか、PSCredential コマンドレットから返されるオブジェクトなど、Get-Credential オブジェクトを含む変数を入力します。ユーザー名のみを入力すると、パスワードの入力を促すメッセージが表示されます。

-PSElapsedTimeoutSec <UInt32>

ワークフローとすべての関連リソースがシステムで維持される期間を決定します。タイムアウトが切れると、ワークフローは処理中であっても削除されます。 10 ~ 4,294,967,295 の値を入力します。デフォルト値の 0 (ゼロ) は、経過タイムアウトがないことを意味します。

-PSParameterCollection <ハッシュテーブル[]>

ターゲットコンピューターごとに異なるワークフロー共通パラメーター値を指定します。

ターゲットコンピューターごとに 1 つのハッシュテーブルを持つハッシュテーブルのコンマ区切りの一覧を入力します。各ハッシュテーブルでは、最初のキーが PSComputerName され、その値はターゲットコンピューターの名前です。コンピューター名にはワイルドカード文字を使用できます。ハッシュテーブル内の残りのキーの場合、キーはパラメーター名であり、値はパラメーター値です。

例えば次が挙げられます。

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

上記の例では、すべての接続のデフォルトの PSElapsedTimeoutSec は 20 秒ですが、Server01 は独自のタイムアウトを 10 秒に指定してデフォルト値を上書きします。

-PSPersist <ブール>

ワークフローで指定されているチェックポイントに加えて、ワークフローにチェックポイントを追加します。

このパラメーターは、ワークフロー内のチェックポイント ( PSPersist アクティビティの共通パラメーター、 Checkpoint-Workflow アクティビティ、または $PSPersistPreference 変数を使用して指定されるチェックポイントなど) を抑制することはできません。

"チェックポイント" または "永続化ポイント" は、ワークフローの実行中にキャプチャされ、ディスクまたは SQL データベースの永続化ストアに保存される、ワークフローの状態とデータのスナップショットです。 Windows PowerShell ワークフローでは、保存されたデータを使用して、ワークフローを再起動するのではなく、最後の永続化ポイントから中断または中断されたワークフローを再開します。

有効な値:

(デフォルト)このパラメーターを省略すると、ワークフローで指定されているチェックポイントに加えて、ワークフローの先頭と末尾にチェックポイントが追加されます。
$True。ワークフローで指定されたチェックポイントに加えて、ワークフローの先頭と末尾にチェックポイントを追加し、各アクティビティの後にチェックポイントを追加します。
$False。チェックポイントは追加されません。チェックポイントは、ワークフローで指定されている場合にのみ取得されます。

●PSPort <Int32>

ターゲットコンピューター上のネットワークポートを指定します。既定のポートは、5985 (HTTP の WinRM ポート) と 5986 (HTTPS の WinRM ポート) です。

PSPort パラメーターは、必要でない限り使用しないでください。コマンドで設定されたポートは、コマンドが実行されるすべてのコンピューターまたはセッションに適用されます。代替ポート設定により、コマンドがすべてのコンピューターで実行できなくなる可能性があります。代替ポートを使用する前に、そのポートでリッスンするようにリモートコンピューター上の WinRM リスナーを構成する必要があります。

-PSPrivateMetadata <ハッシュテーブル>

ワークフロージョブにカスタマイズされた情報を提供します。ハッシュテーブルを入力します。キーと値は、ワークフローごとにカスタマイズされます。ワークフローのプライベートメタデータの詳細については、ワークフローのヘルプトピックを参照してください。

このパラメーターは、Windows PowerShell ワークフローエンジンでは処理されません。代わりに、エンジンはハッシュテーブルをワークフローに直接渡します。

-PSRunningTimeoutSec <UInt32>

ワークフローが中断された時間を除き、ワークフローの実行時間を秒単位で指定します。時間が経過してもワークフローの実行が完了しない場合、Windows PowerShell ワークフローエンジンはワークフローの実行を強制的に停止します。

-PSSessionOption <PSSessionOption>

セッションの詳細オプションをターゲットコンピューターに設定します。 PSSessionOption コマンドレットを使用して作成するオブジェクトなど、New-PSSessionOption オブジェクトを入力します。

セッション・オプションのデフォルト値は、 $PSSessionOption ユーザー設定変数の値 (設定されている場合) によって決まります。それ以外の場合、セッションはセッション構成で指定された値を使用します。

既定値を含むセッションオプションの説明については、 New-PSSessionOption コマンドレットのヘルプトピック (xref:Microsoft.PowerShell.Core.New-PSSessionOption) を参照してください。 $PSSessionOption 基本設定変数の詳細については、about_Preference_Variablesを参照してください。

-PSUseSSL <スイッチパラメータ>

Secure Sockets Layer (SSL) プロトコルを使用して、ターゲットコンピューターへの接続を確立します。既定では、SSL は使用されません。

WS-Management は、ネットワークを介して転送されるすべての Windows PowerShell コンテンツを暗号化します。 UseSSL は、HTTP ではなく HTTPS 経由でデータを送信する追加の保護です。このパラメーターを使用しても、コマンドに使用されているポートで SSL を使用できない場合、コマンドは失敗します。