次の方法で共有

New-PSSessionOption

  • リファレンス
モジュール:
Microsoft.PowerShell.Core

PSSession の詳細設定オプションが格納されたオブジェクトを作成します。

構文

New-PSSessionOption
   [-MaximumRedirection <Int32>]
   [-NoCompression]
   [-NoMachineProfile]
   [-Culture <CultureInfo>]
   [-UICulture <CultureInfo>]
   [-MaximumReceivedDataSizePerCommand <Int32>]
   [-MaximumReceivedObjectSize <Int32>]
   [-OutputBufferingMode <OutputBufferingMode>]
   [-MaxConnectionRetryCount <Int32>]
   [-ApplicationArguments <PSPrimitiveDictionary>]
   [-OpenTimeout <Int32>]
   [-CancelTimeout <Int32>]
   [-IdleTimeout <Int32>]
   [-ProxyAccessType <ProxyAccessType>]
   [-ProxyAuthentication <AuthenticationMechanism>]
   [-ProxyCredential <PSCredential>]
   [-SkipCACheck]
   [-SkipCNCheck]
   [-SkipRevocationCheck]
   [-OperationTimeout <Int32>]
   [-NoEncryption]
   [-UseUTF16]
   [-IncludePortInSPN]
   [<CommonParameters>]

説明

New-PSSessionOption コマンドレットは、ユーザー管理セッション (PSSession) の高度なオプションを含む オブジェクトを作成します。 オブジェクトは、New-PSSession、Enter-PSSession、Invoke-Command などの PSSession を作成するコマンドレットの SessionOption パラメーターの値として使用できます。

パラメーターを指定しない場合、New-PSSessionOption は、すべてのオプションの既定値を格納したオブジェクトを生成します。 プロパティはすべて編集できるため、結果のオブジェクトをテンプレートとして使用して、会社用の標準的なオプション オブジェクトを作成できます。

セッション オプション オブジェクトをユーザー設定変数に $PSSessionOption 保存することもできます。 この変数の値は、セッション オプションの新しい既定値を確立します。 これらの値は、セッションに対してセッション オプションが設定されていない場合に有効になり、セッション構成に設定されたオプションよりも優先されます。ただし、セッション オプションを指定するか、セッションを作成するコマンドレットでセッション オプション オブジェクトを作成することによって、これらの値をオーバーライドすることができます。 基本設定変数の $PSSessionOption 詳細については、「 about_Preference_Variables」を参照してください。

セッションを作成するコマンドレットでセッション オプション オブジェクトを使用すると、セッション オプション値は、$PSSessionOption ユーザー設定変数およびセッション構成に設定されたセッションの既定値よりも優先されます。 ただし、セッション構成で設定された最大値、クォータ、または制限よりも優先されることはありません。 セッション構成の詳細については、「 about_Session_Configurations」を参照してください。

例

例 1: 既定のセッション オプションをCreateする

このコマンドは、すべての既定値を持つセッション オプション オブジェクトを作成します。

New-PSSessionOption

MaximumConnectionRedirectionCount : 5
NoCompression                     : False
NoMachineProfile                  : False
ProxyAccessType                   : IEConfig
ProxyAuthentication               : Negotiate
ProxyCredential                   :
SkipCACheck                       : False
SkipCNCheck                       : False
SkipRevocationCheck               : False
OperationTimeout                  : 00:03:00
NoEncryption                      : False
UseUTF16                          : False
Culture                           :
UICulture                         :
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize         :
ApplicationArguments              :
OpenTimeout                       : 00:03:00
CancelTimeout                     : 00:01:00
IdleTimeout                       : 00:04:00

例 2: セッション オプション オブジェクトを使用してセッションを構成する

この例では、セッション オプション オブジェクトを使用してセッションを構成する方法を示します。

$pso = New-PSSessionOption -Culture "fr-fr" -MaximumReceivedObjectSize 10MB
New-PSSession -ComputerName Server01 -SessionOption $pso

最初のコマンドは、新しいセッション オプション オブジェクトを作成し、変数の $pso 値に保存します。 2 番目のコマンドでは、 コマンドレットを New-PSSession 使用して、Server01 リモート コンピューターにセッションを作成します。 このコマンドは、変数の値の session オプション オブジェクトを $pso 、コマンドの SessionOption パラメーターの値として使用します。

例 3: 対話型セッションを開始する

このコマンドでは、 コマンドレットを Enter-PSSession 使用して、Server01 コンピューターとの対話型セッションを開始します。

Enter-PSSession -ComputerName Server01 -SessionOption (New-PSSessionOption -NoEncryption -NoCompression)

SessionOption パラメーターの値は、New-PSSessionOptionNoEncryption パラメーターと NoCompression パラメーターを持つコマンドです。

コマンドは New-PSSessionOption 、コマンドの前 Enter-PSSession に実行されるようにかっこで囲まれています。

例 4: セッション オプション オブジェクトを変更する

この例では、セッション オプション オブジェクトを変更できることを示します。 すべてのプロパティは、読み取り/書き込み値を持ちます。

$a = New-PSSessionOption
$a.OpenTimeout

Days              : 0
Hours             : 0
Minutes           : 3
Seconds           : 0
Milliseconds      : 0
Ticks             : 1800000000
TotalDays         : 0.00208333333333333
TotalHours        : 0.05
TotalMinutes      : 3
TotalSeconds      : 180
TotalMilliseconds : 180000

$a.UICulture = (Get-UICulture)
$a.OpenTimeout = (New-Timespan -Minutes 4)
$a.MaximumConnectionRedirectionCount = 1
$a

MaximumConnectionRedirectionCount : 1
NoCompression                     : False
NoMachineProfile                  : False
ProxyAccessType                   : IEConfig
ProxyAuthentication               : Negotiate
ProxyCredential                   :
SkipCACheck                       : False
SkipCNCheck                       : False
SkipRevocationCheck               : False
OperationTimeout                  : 00:03:00
NoEncryption                      : False
UseUTF16                          : False
Culture                           :
UICulture                         : en-US
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize         :
ApplicationArguments              :
OpenTimeout                       : 00:04:00
CancelTimeout                     : 00:01:00
IdleTimeout                       : 00:04:00

この方法を使用して、会社の標準のセッション オブジェクトを作成し、特定の用途向けにカスタマイズされたバージョンを作成します。

例 5: ユーザー設定変数をCreateする

このコマンドは、ユーザー設定変数を $PSSessionOption 作成します。

$PSSessionOption = New-PSSessionOption -OpenTimeOut 120000

ユーザー設定変数は$PSSessionOption、セッションで発生すると、および コマンドレットを使用して作成されるセッションのオプションの既定値をNew-PSSessionEnter-PSSessionInvoke-Command設定します。

変数を $PSSessionOption すべてのセッションで使用できるようにするには、それを PowerShell セッションと PowerShell プロファイルに追加します。

基本設定変数の $PSSessionOption 詳細については、「 about_Preference_Variables」を参照してください。 プロファイルの詳細については、「about_Profiles」を参照してください。

例 6: リモート セッション構成の要件を満たす

この例では、SessionOption オブジェクトを使用してリモート セッション構成の要件を満たす方法を示します。

$skipCN = New-PSSessionOption -SkipCNCheck
New-PSSession -ComputerName 171.09.21.207 -UseSSL -Credential Domain01\User01 -SessionOption $SkipCN

最初のコマンドでは、 コマンドレットを New-PSSessionOption 使用して、 SkipCNCheck プロパティを持つセッション オプション オブジェクトを作成します。 コマンドは、結果のセッション オブジェクトを 変数に $skipCN 保存します。

2 番目のコマンドでは、 コマンドレットを New-PSSession 使用して、リモート コンピューターに新しいセッションを作成します。 $skipCN チェック変数は、SessionOption パラメーターの値で使用されます。

コンピューターは IP アドレスによって識別されるため、 ComputerName パラメーターの値は、Secure Sockets Layer (SSL) に使用される証明書のどの共通名にも一致しません。 その結果、SkipCNCheck オプションが必要になります。

例 7: リモート セッションで引数を使用できるようにする

この例では、コマンドレットの ApplicationArguments パラメーターを使用して、 New-PSSessionOption リモート セッションで追加のデータを使用できるようにする方法を示します。

$team = @{Team="IT"; Use="Testing"}
$TeamOption = New-PSSessionOption -ApplicationArguments $team
$s = New-PSSession -ComputerName Server01 -SessionOption $TeamOption
Invoke-Command -Session $s {$PSSenderInfo.ApplicationArguments}

Name                 Value
----                 -----
Team                 IT
Use                  Testing
PSVersionTable       {CLRVersion, BuildVersion, PSVersion, WSManStackVersion...}

Invoke-Command -Session $s {
  if ($PSSenderInfo.ApplicationArguments.Use -ne "Testing") {
    .\logFiles.ps1
  }
  else {
    "Just testing."
  }
}

Just testing.

最初のコマンドは、 Team と Use という 2 つのキーを持つハッシュ テーブルを作成します。 コマンドは、ハッシュ テーブルを 変数に $team 保存します。 ハッシュ テーブルの詳細については、「about_Hash_Tables (ハッシュ テーブルについて)」をご覧ください。

次に、 コマンドレットは New-PSSessionOptionApplicationArguments パラメーターを使用して、 変数に保存されたセッション オプション オブジェクトを $team 作成します。 セッション オプション オブジェクトを作成すると New-PSSessionOption 、 ApplicationArguments パラメーターの値のハッシュ テーブルがプリミティブ ディクショナリに自動的に変換されるため、データをリモート セッションに確実に送信できます。

コマンドレットは New-PSSession 、Server01 コンピューターでセッションを開始します。 SessionOption パラメーターを使用して、変数にオプションを$teamOption含めます。

コマンドレットは Invoke-Command 、変数内のデータが $team リモート セッションのコマンドで使用できる方法を示しています。 データは、自動変数の ApplicationArguments プロパティに $PSSenderInfo 表示されます。

最後 Invoke-Command に、データの使用方法を示します。

パラメーター

-ApplicationArguments

リモート セッションに送信されるプリミティブな辞書を指定します。 セッション構成のスタートアップ スクリプトなど、リモート セッション内のコマンドとスクリプトは、自動変数の ApplicationArguments プロパティでこのディクショナリを $PSSenderInfo 見つけることができます。 このパラメーターを使用すると、リモート セッションにデータを送信することができます。

詳細については、「about_Hash_Tables、about_Session_Configurations、about_Automatic_Variables」を参照してください。

Type:PSPrimitiveDictionary
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-CancelTimeout

取り消し操作 (Ctrl + C) が終了するまで PowerShell が待機する時間を指定します。 値をミリ秒単位で入力します。

既定値は 60,000 (1 分) です。 値 0 (ゼロ) は、タイムアウトがないことを表します。つまり、コマンドは無期限に続行されます。

Type:Int32
Aliases:CancelTimeoutMSec
Position:Named
Default value:60000
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Culture

セッションに使用するカルチャを指定します。 カルチャ名を形式 (例: ja-JP)、<languagecode2>-<country/regioncode2>CultureInfo オブジェクトを含む変数、または CultureInfo オブジェクトを取得するコマンドを入力します。

既定値は で $Null、オペレーティング システムで設定されているカルチャがセッションで使用されます。

Type:CultureInfo
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IdleTimeout

リモート コンピューターがローカル コンピューターから通信を受信しない場合にセッションが開いたままの期間を指定します。 これにはハートビート信号が含まれます。 この期間が経過すると、セッションは閉じられます。

セッションを切断して再接続する場合、アイドル タイムアウト値は非常に重要です。 セッションがタイムアウトしていない場合にのみ再接続することができます。

値をミリ秒単位で入力します。 最小値は 60000 (1 分) です。 最大値は、セッション構成の MaxIdleTimeoutms プロパティの値です。 既定値 -1 では、アイドル タイムアウトは設定されません。

セッションでは、セッション オプションに設定されているアイドルタイムアウト (存在する場合) が使用されます。 何も設定されていない場合 (-1)、セッション構成の IdleTimeoutMs プロパティの値または WSMan シェルタイムアウト値 (WSMan:\<ComputerName>\Shell\IdleTimeout) のどちらか短い方を使用します。

セッション オプションに設定されたアイドル タイムアウトがセッション構成の MaxIdleTimeoutMs プロパティの値を超える場合、セッション作成するコマンドは失敗します。

既定の Microsoft.PowerShell セッション構成の IdleTimeoutMs 値は 7200000 ミリ秒 (2 時間) です。 MaxIdleTimeoutMs の値は2147483647ミリ秒 (>24 日) です。 WSMan シェルのアイドル タイムアウト (WSMan:\<ComputerName>\Shell\IdleTimeout) の既定値は 7200000 ミリ秒 (2 時間) です。

セッションからの切断またはセッションへの再接続時に、セッションのアイドル タイムアウト値を変更することもできます。 詳細については、次のトピックを参照してください。 Disconnect-PSSession および Connect-PSSession

Windows PowerShell 2.0 では、IdleTimeout パラメーターの既定値は 240,000 (4 分) です。

Type:Int32
Aliases:IdleTimeoutMSec
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IncludePortInSPN

Kerberos 認証に使用されるサービス プリンシパル名 (SPN) にポート番号を含めます (例: HTTP://<ComputerName>:5985)。 このオプションを使用すると、クライアントは、既定以外の SPN を使用して、Kerberos 認証を使用するリモート コンピューターに対して認証できます。

このオプションは、Kerberos 認証をサポートする複数のサービスが異なるユーザー アカウントで実行されている企業向けに設計されています。 たとえば、Kerberos 認証を許可する IIS アプリケーションでは、コンピューター アカウントとは異なるユーザー アカウントに既定の SPN を登録する必要があります。 このような場合、PowerShell リモート処理では、コンピューター アカウントに登録されている SPN が必要なため、認証に Kerberos を使用できません。 この問題を解決するために、管理者は、 Setspn.exeを使用 するなど、さまざまなユーザー アカウントに登録され、SPN にポート番号を含めることでそれらを区別できるさまざまな SPN を作成できます。

詳細については、「 Setspn の概要」を参照してください。

このパラメーターは Windows PowerShell 3.0 で導入されました。

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaxConnectionRetryCount

ネットワークの問題が原因で現在の試行が失敗した場合に、PowerShell がターゲット コンピューターへの接続を試行する回数を指定します。 既定値は 5 です。

このパラメーターは、PowerShell バージョン 5.0 用に追加されました。

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaximumReceivedDataSizePerCommand

ローカル コンピューターがリモート コンピューターから 1 つのコマンドで受け取ることができる最大バイト数を指定します。 値をバイト単位で入力します。 既定では、データのサイズに関する制限はありません。

このオプションは、クライアント コンピューター上のリソースを保護するために用意されています。

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaximumReceivedObjectSize

ローカル コンピューターがリモート コンピューターから受信できるオブジェクトの最大サイズを指定します。 このオプションは、クライアント コンピューター上のリソースを保護するために用意されています。 値をバイト単位で入力します。

Windows PowerShell 2.0 では、このパラメーターを省略した場合、オブジェクトのサイズに関する制限はありません。 Windows PowerShell 3.0 以降では、このパラメーターを省略した場合、既定値は 200 MB です。

Type:Int32
Position:Named
Default value:200 MB
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaximumRedirection

接続が失敗するまでに、PowerShell が代替の Uniform Resource Identifier (URI) に接続をリダイレクトする回数を指定します。 既定値は 5 です。 値 0 (ゼロ) を指定した場合、リダイレクトはまったく行われません。

このオプションは、セッションを作成するコマンドで AllowRedirection パラメーターが使用されている場合にのみ、セッションで使用されます。

Type:Int32
Position:Named
Default value:5
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-NoCompression

セッションでのパケットの圧縮を無効にします。 圧縮処理には多くのプロセッサ サイクルが使用されますが、転送が高速化されます。

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-NoEncryption

データの暗号化を無効にします。

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-NoMachineProfile

ユーザーの Windows ユーザー プロファイルを読み込まないようにします。 その場合、セッションをより高速に作成できる可能性がありますが、ユーザー固有のレジストリ設定、環境変数などの項目、および証明書をセッションで使用できなくなります。

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OpenTimeout

セッションの接続が確立されるのをクライアント コンピューターが待機する期間を指定します。 この期間が経過すると、接続を確立するコマンドは失敗します。 値をミリ秒単位で入力します。

既定値は 180,000 (3 分) です。 値 0 (ゼロ) は、タイムアウトがないことを表します。つまり、コマンドは無期限に続行されます。

Type:Int32
Aliases:OpenTimeoutMSec
Position:Named
Default value:180000 (3 minutes)
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OperationTimeout

セッションの任意の操作を実行できる最大時間を決定します。 この期間が経過すると、操作は失敗します。 値をミリ秒単位で入力します。

既定値は 180,000 (3 分) です。 値 0 (ゼロ) は、タイムアウトがないことを表します。つまり、操作は無期限に続行されます。

Type:Int32
Aliases:OperationTimeoutMSec
Position:Named
Default value:180000 (3 minutes)
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OutputBufferingMode

出力バッファーがいっぱいになったときに切断されたセッションでコマンドの出力を管理する方法を指定します。

出力バッファー モードがセッションまたはセッション構成で設定されていない場合、既定値は Block です。 ユーザーは、セッションの切断時に出力バッファー モードを変更することもできます。

このパラメーターを省略すると、セッション オプション オブジェクトの OutputBufferingMode の値は None になります。 値 Block または Drop は、セッション構成に設定された出力バッファー モード トランスポート オプションをオーバーライドします。 このパラメーターの有効値は、次のとおりです。

  • ブロック。 出力バッファーがいっぱいのとき、バッファーが空くまで実行が中断されます。
  • Drop : 出力バッファーがいっぱいのとき、実行は続行されます。 新しい出力が保存されると、最も古い出力が破棄されます。
  • [なし] : 出力バッファー モードが指定されません。

出力バッファリング モードトランスポート オプションの詳細については、「」を参照してください New-PSTransportOption。

このパラメーターは Windows PowerShell 3.0 で導入されました。

Type:OutputBufferingMode
Accepted values:None, Drop, Block
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProxyAccessType

ホスト名の解決に使用するメカニズムを指定します。 このパラメーターの有効値は、次のとおりです。

  • IEConfig
  • WinHttpConfig
  • AutoDetect
  • NoProxyServer
  • なし

既定値は None です。

このパラメーターの値の詳細については、「 ProxyAccessType 列挙」を参照してください。

Type:ProxyAccessType
Accepted values:None, IEConfig, WinHttpConfig, AutoDetect, NoProxyServer
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProxyAuthentication

プロキシの解決に使用する認証方法を指定します。 このパラメーターに使用できる値は、 Basic、 Digest、 Negotiate です。 既定値は Negotiate です。

このパラメーターの値の詳細については、「 AuthenticationMechanism 列挙」を参照してください。

Type:AuthenticationMechanism
Accepted values:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:Named
Default value:Negotiate
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProxyCredential

プロキシ認証に使用する資格情報を指定します。 PSCredential オブジェクトを含む変数、または PSCredential オブジェクトを取得するコマンド (コマンドなど) をGet-Credential入力します。 このオプションを設定しない場合、資格情報は指定されません。

Type:PSCredential
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SkipCACheck

HTTPS 経由で接続するときに、サーバー証明書が信頼された証明機関 (CA) によって署名されていることをクライアントが検証しないことを指定します。

このオプションは、リモート コンピューターが別のメカニズムを使用して信頼されている場合にのみ使用します。たとえば、リモート コンピューターが物理的に安全であり切り離されているネットワークの一部である場合や、WinRM 構成において信頼されるホストとして記載されている場合が該当します。

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SkipCNCheck

サーバーの証明書共通名 (CN) がサーバーのホスト名と一致する必要がないことを指定します。 このオプションは、HTTPS プロトコルを使用するリモート操作でのみ使用されます。

このオプションは、信頼されるコンピューターに対してのみ使用します。

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SkipRevocationCheck

サーバー証明書の失効状態を検証しません。

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-UICulture

セッションに使用する UI カルチャを指定します。

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

  • 形式の <languagecode2>-<country/regioncode2> カルチャ名 (例: ) ja-JP
  • CultureInfo オブジェクトを含む変数
  • CultureInfo オブジェクトを取得するコマンド (例: )Get-Culture

既定値は で $null、セッションの作成時にオペレーティング システムで設定される UI カルチャがセッションで使用されます。

Type:CultureInfo
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-UseUTF16

このコマンドレットが UTF8 形式ではなく UTF16 形式で要求をエンコードすることを示します。

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

入力

None

パイプを使用してこのコマンドレットに入力を渡すことはできません。

出力

PSSessionOption

メモ

PSSession を作成するコマンドで SessionOption パラメーターが使用されていない場合、セッション・オプションは、設定変数の$PSSessionOptionプロパティー値 (設定されている場合) によって決定されます。 変数の $PSSessionOption 詳細については、「 about_Preference_Variables」を参照してください。

セッション構成オブジェクトのプロパティは、セッション構成に設定されているオプションとその値によって異なります。 また、セッション構成ファイルを使用するセッション構成には追加のプロパティがあります。