次の方法で共有


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

説明

New-PSSessionOption コマンドレットは、ユーザー管理セッション (PSSession) の詳細オプションを含むオブジェクトを作成します。 このオブジェクトは、PSSession (New-PSSessionEnter-PSSessionInvoke-Commandなど) を作成するコマンドレットの 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 コマンドです。

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.

最初のコマンドは、 TeamUse の 2 つのキーを持つハッシュ テーブルを作成します。 このコマンドは、ハッシュ テーブルを $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 が取り消し操作 (CTRL+C) が終了するまでの待機時間を指定します。 値をミリ秒単位で入力します。

既定値は 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 プロパティの値を超えると、セッションを作成するコマンドは失敗します。

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

セッションから切断したり、セッションに再接続したりするときに、セッションのアイドル タイムアウト値を変更することもできます。 詳細については、次のトピックを参照してください。 Disconnect-PSSession および Connect-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 を使用できません。 この問題を解決するために、管理者は、異なるユーザー アカウントに登録され、SPN にポート番号を含めることで区別できる異なる SPN ( Setspn.exeの使用など) を作成できます。

詳細については、「 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 の詳細については、 Windows リモート管理のドキュメントを参照してください。

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

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

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

-OutputBufferingMode

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

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

このパラメーターを省略すると、SessionOption オブジェクトの OutputBufferingMode の値がNoneBlockまたは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 オブジェクトを含む変数、または PSCredential オブジェクトを取得するコマンド (Get-Credential コマンドなど) を入力します。 このオプションを設定しない場合、資格情報は指定されません。

型: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 カルチャを指定します。

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

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

既定値は $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」を参照してください。

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