次の方法で共有


New-PSSessionOption

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

説明

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

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

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

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

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

このコマンドは、既定値を使用して SessionOption オブジェクトを作成します。

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: セッション オプション オブジェクトを使用してセッションを構成する

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

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

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

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

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

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

SessionOption パラメーターの値は、NoEncryption と noCompression パラメーターを する コマンドです。

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

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

この例では、SessionOption オブジェクトを変更できることを示します。 すべてのプロパティには、読み取り/書き込み値があります。

$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: 基本設定変数を作成する

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

$PSSessionOption = New-PSSessionOption -OpenTimeOut 120000

セッションで $PSSessionOption 基本設定変数を設定すると、New-PSSessionEnter-PSSession、および Invoke-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 プロパティを持つ SessionOption オブジェクトを作成します。 このコマンドは、結果のセッション オブジェクトを $skipCN 変数に保存します。

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

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

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

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

$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 と Use2 つのキーを持つハッシュ テーブルを作成します。 このコマンドは、ハッシュ テーブルを $team 変数に保存します。 ハッシュ テーブルの詳細については、about_Hash_Tablesを参照してください。

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

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

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

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

パラメーター

-ApplicationArguments

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

詳細については、「about_Hash_Tablesabout_Session_Configurations、および about_Automatic_Variables」を参照してください。

型:PSPrimitiveDictionary
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-CancelTimeout

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

既定値は 60000 (1 分) です。 0 (ゼロ) の値はタイムアウトがないことを意味します。コマンドは無期限に続行されます。

型:Int32
Aliases:CancelTimeoutMSec
配置:Named
規定値:60000
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-Culture

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

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

型:CultureInfo
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-IdleTimeout

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

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

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

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

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

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

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

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

型:Int32
Aliases:IdleTimeoutMSec
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る: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 で導入されました。

型:SwitchParameter
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-MaxConnectionRetryCount

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

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

型:Int32
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-MaximumReceivedDataSizePerCommand

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

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

型:Int32
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-MaximumReceivedObjectSize

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

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

型:Int32
配置:Named
規定値:209715200
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-MaximumRedirection

接続が失敗するまでに、PowerShell が代替 Uniform Resource Identifier (URI) に接続をリダイレクトする回数を決定します。 既定値は 5です。 0 (ゼロ) の値を指定すると、すべてのリダイレクトが禁止されます。

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

型:Int32
配置:Named
規定値:5
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-NoCompression

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

型:SwitchParameter
配置:Named
規定値:False
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-NoEncryption

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

型:SwitchParameter
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-NoMachineProfile

ユーザーの Windows ユーザー プロファイルの読み込みを禁止します。 その結果、セッションの作成が高速化される可能性がありますが、ユーザー固有のレジストリ設定、環境変数などの項目、証明書はセッションで使用できません。

型:SwitchParameter
配置:Named
規定値:False
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-OpenTimeout

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

既定値は 180000 (3 分) です。 0 (ゼロ) の値はタイムアウトがないことを意味します。コマンドは無期限に続行されます。

型:Int32
Aliases:OpenTimeoutMSec
配置:Named
規定値:180000 (3 minutes)
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-OperationTimeout

接続タイムアウトを開始 前に、WinRM がライブ接続からの正の接続テストを待機する最大時間を決定します。WinRM の詳細については、Windows リモート管理のドキュメントを参照してください。

OperationTimeoutリモート セッションで実行されているコマンドやプロセスに時間制限 適用されず、SSH などの他のリモート処理プロトコルに影響 はありません。

既定値は 180000 (3 分) です。 0 (ゼロ) の値は、タイムアウトがないことを意味します。

型:Int32
Aliases:OperationTimeoutMSec
配置:Named
規定値:180000 (3 minutes)
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-OutputBufferingMode

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

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

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

  • Block. 出力バッファーがいっぱいになると、バッファーがクリアされるまで実行が中断されます。
  • Drop. 出力バッファーがいっぱいになると、実行が続行されます。 新しい出力が保存されると、最も古い出力が破棄されます。
  • None. 出力バッファリング モードは指定されません。

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

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

型:OutputBufferingMode
指定可能な値:None, Drop, Block
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-ProxyAccessType

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

  • IEConfig
  • WinHttpConfig
  • AutoDetect
  • NoProxyServer
  • None

既定値は Noneです。

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

型:ProxyAccessType
指定可能な値:None, IEConfig, WinHttpConfig, AutoDetect, NoProxyServer
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-ProxyAuthentication

プロキシ解決に使用する認証方法を指定します。 このパラメーターに使用できる値は次のとおりです。

  • Basic
  • Digest
  • Negotiate

既定値は Negotiateです。

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

型:AuthenticationMechanism
指定可能な値:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
配置:Named
規定値:Negotiate
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-ProxyCredential

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

型:PSCredential
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-SkipCACheck

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

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

型:SwitchParameter
配置:Named
規定値:False
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-SkipCNCheck

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

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

型:SwitchParameter
配置:Named
規定値:False
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-SkipRevocationCheck

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

型:SwitchParameter
配置:Named
規定値:False
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-UICulture

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

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

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

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

型:CultureInfo
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-UseUTF16

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

型:SwitchParameter
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

入力

None

このコマンドレットにオブジェクトをパイプすることはできません。

出力

PSSessionOption

メモ

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

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