Register-PSSessionConfiguration
新しいセッション構成を作成して登録します。
構文
Register-PSSessionConfiguration
[-ProcessorArchitecture <String>]
[-Name] <String>
[-ApplicationBase <String>]
[-RunAsCredential <PSCredential>]
[-ThreadApartmentState <ApartmentState>]
[-ThreadOptions <PSThreadOptions>]
[-AccessMode <PSSessionConfigurationAccessMode>]
[-UseSharedProcess]
[-StartupScript <String>]
[-MaximumReceivedDataSizePerCommandMB <Double>]
[-MaximumReceivedObjectSizeMB <Double>]
[-SecurityDescriptorSddl <String>]
[-ShowSecurityDescriptorUI]
[-Force]
[-NoServiceRestart]
[-PSVersion <Version>]
[-SessionTypeOption <PSSessionTypeOption>]
[-TransportOption <PSTransportOption>]
[-ModulesToImport <Object[]>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Register-PSSessionConfiguration
[-ProcessorArchitecture <String>]
[-Name] <String>
[-AssemblyName] <String>
[-ApplicationBase <String>]
[-ConfigurationTypeName] <String>
[-RunAsCredential <PSCredential>]
[-ThreadApartmentState <ApartmentState>]
[-ThreadOptions <PSThreadOptions>]
[-AccessMode <PSSessionConfigurationAccessMode>]
[-UseSharedProcess]
[-StartupScript <String>]
[-MaximumReceivedDataSizePerCommandMB <Double>]
[-MaximumReceivedObjectSizeMB <Double>]
[-SecurityDescriptorSddl <String>]
[-ShowSecurityDescriptorUI]
[-Force]
[-NoServiceRestart]
[-PSVersion <Version>]
[-SessionTypeOption <PSSessionTypeOption>]
[-TransportOption <PSTransportOption>]
[-ModulesToImport <Object[]>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Register-PSSessionConfiguration
[-ProcessorArchitecture <String>]
[-Name] <String>
[-RunAsCredential <PSCredential>]
[-ThreadApartmentState <ApartmentState>]
[-ThreadOptions <PSThreadOptions>]
[-AccessMode <PSSessionConfigurationAccessMode>]
[-UseSharedProcess]
[-StartupScript <String>]
[-MaximumReceivedDataSizePerCommandMB <Double>]
[-MaximumReceivedObjectSizeMB <Double>]
[-SecurityDescriptorSddl <String>]
[-ShowSecurityDescriptorUI]
[-Force]
[-NoServiceRestart]
[-TransportOption <PSTransportOption>]
-Path <String>
[-WhatIf]
[-Confirm]
[<CommonParameters>]
説明
このコマンドレットは、Windows プラットフォームでのみ使用できます。
このコマンドレットは Register-PSSessionConfiguration
、ローカル コンピューターに新しいセッション構成を作成して登録します。 これは、リモート ユーザーのカスタム セッションを作成するために使用できる高度なコマンドレットです。
すべての PowerShell セッション (PSSession) は、エンドポイントとも呼ばれるセッション構成を使用します。 ユーザーは、コンピューターに接続するセッションを作成するときに、セッション構成を選択するか、PowerShell リモート処理を有効にしたときに登録された既定のセッション構成を使用できます。 ユーザーは、$PSSessionConfigurationName基本設定変数を設定することもできます。この変数は、現在のセッションで作成されたリモート セッションの既定の構成を指定します。
このセッション構成は、リモート セッションの環境を定義します。 この構成により、セッションで使用できるコマンドおよび言語要素を決定できます。これには、セッションがリモートで取得できる 1 つのオブジェクトまたはコマンド内のデータの量を制限する設定など、コンピューターを保護する設定を含めることができます。 セッション構成のセキュリティ記述子によって、セッション構成を使用するアクセス許可を持つユーザーが決まります。
構成の要素を定義するには、新しい構成クラスを実装するアセンブリを使用するか、セッションで実行されるスクリプトを使用します。 PowerShell 3.0 以降では、セッション構成ファイルを使用してセッション構成を定義することもできます。
セッション構成の詳細については、about_Session_Configurationsを参照してください。 セッション構成ファイルの詳細については、about_Session_Configuration_Filesを参照してください。
例
例 1: NewShell セッション構成を登録する
この例では、NewShell セッション構成を登録します。 AssemblyName パラメーターと ApplicationBase パラメーターは、セッション構成のコマンドレットとプロバイダーを指定するMyShell.dll ファイルの場所を指定します。 ConfigurationTypeName パラメーターは、アセンブリから使用する構成クラスを指定します。
$sessionConfiguration = @{
Name='NewShell'
ApplicationBase='c:\MyShells\'
AssemblyName='MyShell.dll'
ConfigurationTypeName='MyClass'
}
Register-PSSessionConfiguration @sessionConfiguration
この構成を使用するには、「.」と入力します New-PSSession -ConfigurationName newshell
。
例 2: MaintenanceShell セッション構成を登録する
次の使用例は、 MaintenanceShell セッション構成をローカル コンピューターに登録します。 StartupScript パラメーターはスクリプトをMaintenance.ps1
指定します。
Register-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1
ユーザーがコマンドをNew-PSSession
使用して MaintenanceShell 構成を選択すると、スクリプトはMaintenance.ps1
新しいセッションで実行されます。 スクリプトはセッションを構成できます。 これには、モジュールのインポートとセッションの実行ポリシーの設定が含まれます。 終了しないエラーを含むエラーがスクリプトによって生成された場合、コマンドは New-PSSession
失敗します。
例 3: セッション構成を登録する
この例では、管理Shell セッション構成を登録します。
変数は $sessionParams
、すべてのパラメーター値を含むハッシュテーブルです。 このハッシュテーブルは、PowerShell スプラッティングを使用してコマンドレットに渡されます。 このコマンドではRegister-PSSessionConfiguration
、SecurityDescritorSDDL パラメーターを使用して、変数の$sddl
値に SDDL を指定し、MaximumReceivedObjectSize MB (メガバイト) パラメーターを使用してオブジェクト サイズの制限を増やします。 また、StartupScript パラメーターを使用して、セッションを構成するスクリプトを指定します。
$sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FASA;GWGX;;;WD)"
$sessionParams = @{
Name="AdminShell"
SecurityDescriptorSDDL=$sddl
MaximumReceivedObjectSizeMB=20
StartupScript="C:\scripts\AdminShell.ps1"
}
Register-PSSessionConfiguration @sessionParams
例 4: 構成要素コンテナー要素を返す
この例では、MaintenanceShell 構成を登録する方法を示します。
Register-PSSessionConfiguration
は、変数に 格納されている WSManConfigContainerElement オブジェクトを $s
返します。 Format-List
は、返されたオブジェクトのすべてのプロパティを表示します。 PSPath プロパティは、オブジェクトが WSMan: ドライブのディレクトリに格納されていることを示します。 Get-ChildItem
(エイリアス dir
)には、パス内の項目が WSMan:\LocalHost\PlugIn
表示されます。 これには、新しい MaintenanceShell 構成と、PowerShell に付属する 2 つの既定の構成が含まれます。
$s = Register-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1
$s | Format-List -Property *
dir WSMan:\LocalHost\Plugin
PSPath : Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell
PSParentPath : Microsoft.WSMan.Management\WSMan::localhost\Plugin
PSChildName : MaintenanceShell
PSDrive : WSMan
PSProvider : Microsoft.WSMan.Management\WSMan
PSIsContainer : True
Keys : {Name=MaintenanceShell}
Name : MaintenanceShell
TypeNameOfElement : Container
Name Type Keys
---- ---- ----
MaintenanceShell Container {Name=MaintenanceShell}
microsoft.powershell Container {Name=microsoft.powershell}
microsoft.powershell32 Container {Name=microsoft.powershell32}
例 5: スタートアップ スクリプトを使用してセッション構成を登録する
この例では、WithProfile セッション構成を作成して登録します。 StartupScript パラメーターは、セッション構成を使用するすべてのセッションに対して、指定されたスクリプトを実行するように PowerShell に指示します。
Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.ps1
このスクリプトには、ドット ソーシングを使用して、セッションの現在のスコープでユーザーの CurrentUserAllHosts プロファイルを実行する 1 つのコマンドが含まれています。
プロファイルの詳細については、「about_Profiles」を参照してください。 ドット ソーシングの詳細については、「about_Scopes」を参照してください。
パラメーター
-AccessMode
セッション構成を有効化および無効化し、コンピューター上のリモート セッションまたはローカル セッションにセッション構成を使用できるかどうかを決定します。 このパラメーターの有効値は、次のとおりです。
- Disabled。 セッション構成を無効にします。 コンピューターへのリモート アクセスまたはローカル アクセスに使用できません。
- ローカル。 ローカル コンピューターのユーザーがセッション構成を使用して同じコンピューター上にローカル ループバック セッションを作成できるようにしますが、リモート ユーザーへのアクセスは拒否されます。
- リモート。 ローカル ユーザーおよびリモート ユーザーは、セッション構成を使用して、このコンピューターでセッションを作成し、コマンドを実行できます。
既定値は Remote です。
他のコマンドレットは、後でこのパラメーターの値をオーバーライドできます。 たとえば、 Enable-PSRemoting
コマンドレットはすべてのセッション構成へのリモート アクセスを許可し、コマンドレットは Enable-PSSessionConfiguration
セッション構成を Disable-PSRemoting
有効にし、コマンドレットはすべてのセッション構成へのリモート アクセスを禁止します。
このパラメーターは PowerShell 3.0 で導入されました。
Type: | PSSessionConfigurationAccessMode |
Accepted values: | Disabled, Local, Remote |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ApplicationBase
AssemblyName パラメーターの値に指定するアセンブリ ファイル (*.dll) のパスを指定します。 AssemblyName パラメーターの値にパスが含まれていない場合は、このパラメーターを使用します。 既定値は、現在のディレクトリです。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-AssemblyName
構成の種類が定義されているアセンブリ ファイル (*.dll) の名前を指定します。 このパラメーターまたは ApplicationBase パラメーターの値で、.dllのパスを指定できます。
このパラメーターは、ConfigurationTypeName パラメーターを指定するときに必要です。
Type: | String |
Position: | 1 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ConfigurationTypeName
この構成に使用される Microsoft .NET Framework の型の完全修飾名を指定します。 指定する型は、System.Management.Automation.Remoting.PSSessionConfiguration クラスを実装する必要があります。
構成の種類を実装するアセンブリ ファイル (*.dll) を指定するには、AssemblyName パラメーターと ApplicationBase パラメーターを指定します。
型を作成すると、コマンドレットの特定のパラメーターの公開や非表示、ユーザーがオーバーライドできないデータ サイズとオブジェクト サイズの制限の設定など、セッション構成のより多くの側面を制御できます。
このパラメーターを省略すると、セッション構成に DefaultRemotePowerShellConfiguration クラスが使用されます。
Type: | String |
Position: | 2 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Confirm
コマンドレットの実行前に確認を求めるメッセージが表示されます。
Type: | SwitchParameter |
Aliases: | cf |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Force
すべてのユーザー プロンプトを抑制し、プロンプトを 表示せずに WinRM サービスを再起動します。 サービスを再起動すると、構成の変更が有効になります。
再起動を防ぎ、再起動プロンプトを表示しないようにするには、NoServiceRestart パラメーターを指定します。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumReceivedDataSizePerCommandMB
任意の 1 つのリモート コマンドでこのコンピューターに送信できるデータ量の制限を指定します。 データ サイズはメガバイト (MB) 単位で入力します。 既定値は 50 MB (メガバイト)です。
ConfigurationTypeName パラメーターで指定されている構成の種類でデータ サイズの制限が定義されている場合、構成の種類の制限が使用され、このパラメーターの値は無視されます。
Type: | Nullable<T>[Double] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumReceivedObjectSizeMB
任意の 1 つのオブジェクトでこのコンピューターに送信できるデータの量の制限を指定します。 データ サイズをメガバイト単位で入力します。 既定値は 10 MB (メガバイト)です。
ConfigurationTypeName パラメーターで指定されている構成の種類でオブジェクト サイズの制限が定義されている場合、構成の種類の制限が使用され、このパラメーターの値は無視されます。
Type: | Nullable<T>[Double] |
Position: | Named |
Default value: | 10 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ModulesToImport
セッション構成を使用するセッションに自動的にインポートされるモジュールを指定します。
既定では、Microsoft.PowerShell.Core のみがセッションにインポートされます。 コマンドレットが除外されない限り、セッションにモジュールを追加するために使用 Import-Module
できます。
このパラメーター値で指定されたモジュールは、SessionType パラメーターで指定されたモジュールと、セッション構成ファイル (New-PSSessionConfigurationFile
) の ModulesToImport キーにリストされているモジュールに加えてインポートされます。 ただし、セッション構成ファイル内の設定によって、モジュールでエクスポートされたコマンドが非表示になったり、ユーザーが使用できなくなったりすることがあります。
このパラメーターは PowerShell 3.0 で導入されました。
Type: | Object[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Name
セッション構成の名前を指定します。 このパラメーターは必須です。
Type: | String |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-NoServiceRestart
WinRM サービスを再起動せず、サービスの再起動を求めるメッセージを表示しません。
既定では、コマンドをRegister-PSSessionConfiguration
実行すると、新しいセッション構成を有効にするために WinRM サービスを再起動するように求められます。 WinRM サービスが再起動されるまで、新しいセッション構成は有効ではありません。
プロンプトを表示せずに WinRM サービスを再起動するには、Force パラメーターを指定します。 WinRM サービスを手動で再起動するには、コマンドレットをRestart-Service
使用します。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Path
セッション構成ファイル (.pssc) New-PSSessionConfigurationFile
のパスとファイル名を指定します (例: . パスを省略した場合、既定値は現在のディレクトリになります。
このパラメーターは PowerShell 3.0 で導入されました。
Type: | String |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProcessorArchitecture
このセッション構成を使用するセッションで、PowerShell プロセスの 32 ビットバージョンと 64 ビット バージョンのどちらを開始するかを決定します。 このパラメーターに使用できる値は、x86 (32 ビット) と AMD64 (64 ビット) です。 既定値は、セッション構成をホストするプロセッサ アーキテクチャにより決定されます。
このパラメーターを使用すると、64 ビット コンピューターで 32 ビット セッションを作成できます。 32 ビット コンピューターでの 64 ビット プロセスの作成を試行します。
Type: | String |
Aliases: | PA |
Accepted values: | x86, amd64 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PSVersion
このセッション構成を使用するセッションの PowerShell のバージョンを指定します。
このパラメーターの値は、セッション構成ファイル内の PowerShellVersion キーの値よりも優先されます。
このパラメーターは PowerShell 3.0 で導入されました。
Type: | Version |
Aliases: | PowerShellVersion |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-RunAsCredential
セッション内のコマンドの資格情報を指定します。 既定では、コマンドは現在のユーザーのアクセス許可で実行されます。
このパラメーターは PowerShell 3.0 で導入されました。
Type: | PSCredential |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SecurityDescriptorSddl
構成のセキュリティ記述子定義言語 (SDDL) 文字列を指定します。
この文字列によって、新しいセッション構成を使用するために必要なアクセス許可が決定します。 セッションでセッション構成を使用するには、少なくとも構成に対する実行 (呼び出し) アクセス許可がユーザーに付与されている必要があります。
セキュリティ記述子が複雑な場合は、このパラメーターの代わりに ShowSecurityDescriptorUI パラメーターを使用することを検討してください。 両方のパラメーターを同じコマンドで使用することはできません。
このパラメーターを省略すると、WinRM サービスのルート SDDL がこの構成に使用されます。
ルート SDDL を表示または変更するには、WSMan プロバイダーを使用します。 たとえば、「 Get-Item wsman:\localhost\service\rootSDDL
」のように指定します。 WSMan プロバイダーの詳細については、「.」と入力します Get-Help wsman
。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SessionTypeOption
セッション構成の種類固有のオプションを指定します。 コマンドレットから返される PSWorkflowExecutionOption オブジェクトなど、セッションの種類の オプション オブジェクトを New-PSWorkflowExecutionOption
入力します。
セッション構成を使用するセッションのオプションは、セッション オプションの値とセッション構成オプションによって決定されます。 指定しない限り、コマンドレットを使用するなどしてセッションで設定された New-PSSessionOption
オプションは、セッション構成で設定されたオプションよりも優先されます。 ただし、セッション オプションの値は、セッション構成に設定されている最大値を超えることはできません。
このパラメーターは PowerShell 3.0 で導入されました。
Type: | PSSessionTypeOption |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ShowSecurityDescriptorUI
このコマンドレットは、セッション構成の SDDL を作成するのに役立つプロパティ シートを表示することを示します。 コマンドを入力し、WinRM サービスをRegister-PSSessionConfiguration
再起動すると、プロパティ シートが表示されます。
構成のアクセス許可を設定するときは、セッションでセッション構成を使用するには、ユーザーに少なくとも実行 (呼び出し) アクセス許可が必要です。
SecurityDescriptorSDDL パラメーターとこのパラメーターを同じコマンドで使用することはできません。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-StartupScript
PowerShell スクリプトの完全修飾パスを指定します。 指定されたスクリプトが、セッション構成を使用する新しいセッションで実行されます。
このスクリプトを使用して、セッションをさらに構成できます。 スクリプトでエラーが生成された場合 (終了しないエラーであっても)、セッションは作成されず、コマンドは New-PSSession
失敗します。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ThreadApartmentState
使用するスレッド モジュールのアパートメント状態を指定します。 使用可能な値は次のとおりです。
- Unknown
- MTA
- STA
Type: | ApartmentState |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ThreadOptions
セッションでコマンドを実行するときにスレッドを作成して使用する方法を指定します。 このパラメーターの有効値は、次のとおりです。
- 既定値
- ReuseThread
- UseCurrentThread
- UseNewThread
既定値は UseCurrentThread です。
詳細については、「PSThreadOptions 列挙型」を参照してください。
Type: | PSThreadOptions |
Accepted values: | Default, UseNewThread, ReuseThread, UseCurrentThread |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-TransportOption
トランスポート オプションを指定します。
このパラメーターは PowerShell 3.0 で導入されました。
Type: | PSTransportOption |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UseSharedProcess
プロセスを 1 つだけ使用して、同じユーザーによって起動され、同じのセッション構成を使用するすべてのセッションをホストします。 既定では、各セッションは、個別のプロセスでホストされます。
このパラメーターは PowerShell 3.0 で導入されました。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-WhatIf
コマンドレットの実行時に発生する内容を示します。 このコマンドレットは実行されません。
Type: | SwitchParameter |
Aliases: | wi |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
入力
None
このコマンドレットにオブジェクトをパイプすることはできません。
出力
メモ
このコマンドレットは、Windows プラットフォームでのみ使用できます。
このコマンドレットを実行するには、[管理者として実行] オプションを使用して PowerShell を起動する必要があります。
このコマンドレットは、Web Services for Management (WS-Management) プラグイン構成を表す XML を生成し、ローカル コンピューター (New-Item wsman:\localhost\plugin
) にプラグインを登録する WS-Management に XML を送信します。
セッション構成オブジェクトのプロパティは、セッション構成に設定されているオプションとその値によって異なります。 また、セッション構成ファイルを使用するセッション構成には追加のプロパティがあります。
関連リンク
PowerShell
フィードバック
https://aka.ms/ContentUserFeedback。
近日公開予定: 2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub イシューを段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、以下を参照してください:フィードバックの送信と表示