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 を作成するコマンドレットの SessionOption パラメーターの値として使用できます (例: New-PSSession
,Enter-PSSession
、Invoke-Command
、 .
パラメーターを指定しない場合、 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 リモート コンピューター上にセッションを作成します。 このコマンドは、変数の値で SessionOption オブジェクトを$pso
コマンドの SessionOption パラメーターの値として使用します。
例 3: 対話型セッションを開始する
このコマンドは、このコマンドレットを Enter-PSSession
使用して、Server01 コンピューターとの対話型セッションを開始します。
Enter-PSSession -ComputerName Server01 -SessionOption (New-PSSessionOption -NoEncryption -NoCompression)
SessionOption パラメーターの値は、New-PSSessionOption
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
セッションで基本設定変数を設定すると、,,およびInvoke-Command
コマンドレットを使用してNew-PSSession
Enter-PSSession
作成されるセッションのオプションのデフォルト値が設定されます。
変数を $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
チェック変数は、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-PSSessionOption
、ApplicationArguments パラメーターを使用して、変数に保存された SessionOption オブジェクトを$team
作成します。 セッション オプション オブジェクトを作成するとNew-PSSessionOption
、ApplicationArguments パラメーターの値のハッシュ テーブルが PrimitiveDictionary に自動的に変換されるため、データをリモート セッションに確実に送信できます。
このコマンドレットは New-PSSession
、Server01 コンピューターでセッションを開始します。 SessionOption パラメーターを使用して、変数にオプションを$teamOption
含めます。
このコマンドレットは Invoke-Command
、リモート セッションのコマンドで変数内 $team
のデータを使用できる方法を示しています。 データは、自動変数の ApplicationArguments プロパティに $PSSenderInfo
表示されます。
最後 Invoke-Command
に、データの使用方法を示します。
パラメーター
-ApplicationArguments
リモート セッションに 送信される PrimitiveDictionary を指定します。 リモート セッションのコマンドとスクリプト (セッション構成のスタートアップ スクリプトを含む) は、自動変数の 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 が待機する時間を指定します。 値をミリ秒単位で入力します。
既定値は 60000
(1 分) です。 値 0
(ゼロ) はタイムアウトがないことを意味します。コマンドは無期限に続行されます。
Type: | Int32 |
Aliases: | CancelTimeoutMSec |
Position: | Named |
Default value: | 60000 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Culture
セッションに使用するカルチャを指定します。 カルチャ名<languagecode2>-<country/regioncode2>
を形式 (例: ja-JP
)、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 シェルのアイドルタイムアウト () の既定値は7200000
ミリ秒 (WSMan:\<ComputerName>\Shell\IdleTimeout
2 時間) です。
セッションから切断したり、セッションに再接続したりするときに、セッションのアイドル タイムアウト値を変更することもできます。 詳細については、次のトピックを参照してください。 Disconnect-PSSession
および Connect-PSSession
Windows PowerShell 2.0 では、IdleTimeout パラメーターの既定値は 240000
(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 を使用できません。 この問題を解決するために、管理者は、異なるユーザー アカウントに登録されている別の SPN (使用 Setspn.exe
など) を作成し、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 以降では、このパラメーターを省略した場合、既定値は 209715200
バイト (または 200MB
) です。
Type: | Int32 |
Position: | Named |
Default value: | 209715200 |
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
セッションの接続が確立されるのをクライアント コンピューターが待機する期間を指定します。 この期間が経過すると、接続を確立するコマンドは失敗します。 値をミリ秒単位で入力します。
既定値は 180000
(3 分) です。 値 0
(ゼロ) はタイムアウトがないことを意味します。コマンドは無期限に続行されます。
Type: | Int32 |
Aliases: | OpenTimeoutMSec |
Position: | Named |
Default value: | 180000 (3 minutes) |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-OperationTimeout
接続タイムアウトを開始する前に、WinRM がライブ接続からの正の接続テストを待機する最大時間を決定します。WinRM の詳細については、Windows リモート管理のドキュメントを参照してください。
OperationTimeout では、リモート セッションで実行されているコマンドまたはプロセスに時間制限は適用されず、SSH などの他のリモート処理プロトコルには影響しません。
既定値は 180000
(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
. ユーザーは、セッションの切断時に出力バッファー モードを変更することもできます。
このパラメーターを省略した場合、SessionOption オブジェクトの OutputBufferingMode の値は None
. セッション構成で Block
設定された出力バッファリング モードトランスポート オプションの値または Drop
オーバーライド。 このパラメーターの有効値は、次のとおりです。
Block
. 出力バッファーがいっぱいのとき、バッファーが空くまで実行が中断されます。Drop
. 出力バッファーがいっぱいのとき、実行は続行されます。 新しい出力が保存されると、最も古い出力が破棄されます。None
. 出力バッファー モードが指定されません。
出力バッファリング・モード・トランスポート・オプションの詳細については、以下を参照してください 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
既定値は 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
このコマンドレットにオブジェクトをパイプすることはできません。
出力
メモ
PSSession を作成するコマンドで SessionOption パラメーターが使用されていない場合、セッション・オプションは設定変数の$PSSessionOption
プロパティー値 (設定されている場合) によって決まります。 $PSSessionOption
変数の詳細については、「about_Preference_Variables」を参照してください。
セッション構成オブジェクトのプロパティは、セッション構成に設定されているオプションとその値によって異なります。 また、セッション構成ファイルを使用するセッション構成には追加のプロパティがあります。
関連リンク
PowerShell
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示