Register-PSSessionConfiguration

リファレンス

モジュール:: Microsoft.PowerShell.Core

新しいセッション構成を作成して登録します。

構文

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: セッション構成を登録する

この例では、 AdminShell セッション構成を登録します。

$sessionParams変数は、すべてのパラメーター値を含むハッシュテーブルです。このハッシュテーブルは、PowerShell スプラッティングを使用してコマンドレットに渡されます。 Register-PSSessionConfiguration コマンドでは、SecurityDescritorSDDL パラメーターを使用して、$sddl変数の値に SDDL を指定し、MaximumReceivedObjectSizeMB パラメーターを使用してオブジェクトサイズの制限を増やします。また、 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は、$s変数に格納されているWSManConfigContainerElement オブジェクトを返します。 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 で導入されました。

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

-ApplicationBase

AssemblyName パラメーターの値で指定されるアセンブリファイル (*.dll) のパスを指定します。このパラメーターは、 AssemblyName パラメーターの値にパスが含まれていない場合に使用します。既定値は、現在のディレクトリです。

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

-AssemblyName

構成の種類が定義されているアセンブリファイル (*.dll) の名前を指定します。このパラメーターまたは ApplicationBase パラメーターの値で、.dllのパスを指定できます。

このパラメーターは、 ConfigurationTypeName パラメーターを指定するときに必要です。

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

-ConfigurationTypeName

この構成に使用される Microsoft .NET Framework 型の完全修飾名を指定します。指定する型は、 System.Management.Automation.Remoting.PSSessionConfiguration クラスを実装する必要があります。

構成の種類を実装するアセンブリファイル (*.dll) を指定するには、 AssemblyName および ApplicationBase パラメーターを指定します。

型を作成すると、コマンドレットの特定のパラメーターの公開や非表示、ユーザーがオーバーライドできないデータサイズとオブジェクトサイズの制限の設定など、セッション構成のより多くの側面を制御できます。

このパラメーターを省略すると、セッション構成に DefaultRemotePowerShellConfiguration クラスが使用されます。

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

-Confirm

コマンドレットの実行前に確認を求めるメッセージが表示されます。

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

-Force

すべてのユーザープロンプトを抑制し、プロンプトを表示せずに WinRM サービスを再起動します。サービスを再起動すると、構成の変更が有効になります。

再起動を防ぎ、再起動プロンプトを表示しないようにするには、 NoServiceRestart パラメーターを指定します。

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

-MaximumReceivedDataSizePerCommandMB

任意の 1 つのリモートコマンドでこのコンピューターに送信できるデータ量の制限を指定します。データサイズはメガバイト (MB) 単位で入力します。既定値は 50 MB です。

ConfigurationTypeName パラメーターで指定された構成の種類でデータサイズの制限が定義されている場合、構成の種類の制限が使用され、このパラメーターの値は無視されます。

型:	Nullable<T>[Double]
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-MaximumReceivedObjectSizeMB

任意の 1 つのオブジェクトでこのコンピューターに送信できるデータの量の制限を指定します。データサイズをメガバイト単位で入力します。既定値は 10 MB です。

ConfigurationTypeName パラメーターで指定されている構成の種類にオブジェクトサイズの制限が定義されている場合、構成の種類の制限が使用され、このパラメーターの値は無視されます。

型:	Nullable<T>[Double]
配置:	Named
規定値:	10
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-ModulesToImport

セッション構成を使用するセッションに自動的にインポートされるモジュールを指定します。

既定では、 Microsoft.PowerShell.Core のみがセッションにインポートされます。コマンドレットが除外されていない限り、 Import-Module を使用してセッションにモジュールを追加できます。

このパラメーター値で指定されたモジュールは、SessionType パラメーターで指定されたモジュールと、セッション構成ファイル (New-PSSessionConfigurationFile) の ModulesToImport キーにリストされているモジュールに加えてインポートされます。ただし、セッション構成ファイル内の設定によって、モジュールでエクスポートされたコマンドが非表示になったり、ユーザーが使用できなくなったりすることがあります。

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

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

-Name

セッション構成の名前を指定します。このパラメーターは必須です。

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

-NoServiceRestart

このパラメーターの目的は、 WinRM サービスの再起動を防ぐことです。この機能はまだ実装されていません。

この機能は、PowerShell 7.5.0-preview.4 で実装されました。

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

-Path

セッション構成ファイル (.pssc) のパスとファイル名 ( New-PSSessionConfigurationFile によって作成されたものなど) を指定します。パスを省略した場合、既定値は現在のディレクトリになります。

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

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

-ProcessorArchitecture

このセッション構成を使用するセッションで、PowerShell プロセスの 32 ビットバージョンと 64 ビットバージョンのどちらを開始するかを決定します。このパラメーターに使用できる値は、x86 (32 ビット) と AMD64 (64 ビット) です。既定値は、セッション構成をホストするプロセッサアーキテクチャにより決定されます。

このパラメーターを使用すると、64 ビットコンピューターで 32 ビットセッションを作成できます。 32 ビットコンピューターでの 64 ビットプロセスの作成を試行します。

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

-PSVersion

このセッション構成を使用するセッションの PowerShell のバージョンを指定します。

このパラメーターの値は、セッション構成ファイルの PowerShellVersion キーの値よりも優先されます。

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

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

-RunAsCredential

セッション内のコマンドの資格情報を指定します。既定では、コマンドは現在のユーザーのアクセス許可で実行されます。

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

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

-SecurityDescriptorSddl

構成のセキュリティ記述子定義言語 (SDDL) 文字列を指定します。

この文字列によって、新しいセッション構成を使用するために必要なアクセス許可が決定します。セッションでセッション構成を使用するには、少なくとも構成に対する実行 (呼び出し) アクセス許可がユーザーに付与されている必要があります。

セキュリティ記述子が複雑な場合は、このパラメーターの代わりに ShowSecurityDescriptorUI パラメーターを使用することを検討してください。同じコマンドで両方のパラメーターを使用することはできません。

このパラメーターを省略すると、 WinRM サービスのルート SDDL がこの構成に使用されます。ルート SDDL を表示または変更するには、WSMan プロバイダーを使用します。たとえば、「 Get-Item wsman:\localhost\service\rootSDDL 」のように指定します。 WSMan プロバイダーの詳細については、「 Get-Help wsman」と入力します。

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

-SessionTypeOption

セッション構成の種類固有のオプションを指定します。 New-PSWorkflowExecutionOption コマンドレットが返すPSWorkflowExecutionOption オブジェクトなどのセッションの種類のオプションオブジェクトを入力します。

セッション構成を使用するセッションのオプションは、セッションオプションの値とセッション構成オプションによって決定されます。指定しない限り、セッションで設定されたオプション ( New-PSSessionOption コマンドレットの使用など) は、セッション構成で設定されたオプションよりも優先されます。ただし、セッションオプションの値は、セッション構成で設定された最大値を超えることはできません。

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

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

-ShowSecurityDescriptorUI

このコマンドレットは、セッション構成の SDDL を作成するのに役立つプロパティシートを表示することを示します。プロパティシートは、 Register-PSSessionConfiguration コマンドを入力し、 WinRM サービスを再起動した後に表示されます。

構成のアクセス許可を設定するときは、セッションでセッション構成を使用するには、ユーザーに少なくとも実行 (呼び出し) アクセス許可が必要です。

同じコマンドで SecurityDescriptorSDDL パラメーターとこのパラメーターを使用することはできません。

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

-StartupScript

PowerShell スクリプトの完全修飾パスを指定します。指定されたスクリプトが、セッション構成を使用する新しいセッションで実行されます。

このスクリプトを使用して、セッションをさらに構成できます。スクリプトでエラーが生成された場合 (終了しないエラーであっても)、セッションは作成されず、 New-PSSession コマンドは失敗します。

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

-ThreadApartmentState

使用するスレッドモジュールのアパートメント状態を指定します。使用可能な値は次のとおりです。

Unknown
MTA
STA

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

-ThreadOptions

セッションでコマンドを実行するときにスレッドを作成して使用する方法を指定します。このパラメーターの有効値は、次のとおりです。

既定値
ReuseThread
UseCurrentThread
UseNewThread

既定値は UseCurrentThread です。

詳細については、「 PSThreadOptions 列挙型を参照してください。

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

-TransportOption

トランスポートオプションを指定します。

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

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

-UseSharedProcess

プロセスを 1 つだけ使用して、同じユーザーによって起動され、同じのセッション構成を使用するすべてのセッションをホストします。既定では、各セッションは、個別のプロセスでホストされます。

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

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

-WhatIf

コマンドレットの実行時に発生する内容を示します。コマンドレットは実行されません。

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

入力

None

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

出力

WSManConfigContainerElement

メモ

このコマンドレットは、Windows プラットフォームでのみ使用できます。

このコマンドレットを実行するには、 管理者として実行 オプションを使用して PowerShell を起動する必要があります。

このコマンドレットは、Web Services for Management (WS-Management) プラグイン構成を表す XML を生成し、ローカルコンピューター (New-Item wsman:\localhost\plugin) にプラグインを登録する WS-Management に XML を送信します。

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

次の方法で共有

Register-PSSessionConfiguration

構文

説明

例

例 1: NewShell セッション構成を登録する

例 2: MaintenanceShell セッション構成を登録する

例 3: セッション構成を登録する

例 4: 構成要素コンテナー要素を返す

例 5: スタートアップスクリプトを使用してセッション構成を登録する

パラメーター

-AccessMode

-ApplicationBase

-AssemblyName

-ConfigurationTypeName

-Confirm

-Force

-MaximumReceivedDataSizePerCommandMB

-MaximumReceivedObjectSizeMB

-ModulesToImport

-Name

-NoServiceRestart

-Path

-ProcessorArchitecture

-PSVersion

-RunAsCredential

-SecurityDescriptorSddl

-SessionTypeOption

-ShowSecurityDescriptorUI

-StartupScript

-ThreadApartmentState

-ThreadOptions

-TransportOption

-UseSharedProcess

-WhatIf

入力

出力

メモ

その他のリソース

次の方法で共有

Register-PSSessionConfiguration

構文

説明

例

例 1: NewShell セッション構成を登録する

例 2: MaintenanceShell セッション構成を登録する

例 3: セッション構成を登録する

例 4: 構成要素コンテナー要素を返す

例 5: スタートアップ スクリプトを使用してセッション構成を登録する

パラメーター

-AccessMode

-ApplicationBase

-AssemblyName

-ConfigurationTypeName

-Confirm

-Force

-MaximumReceivedDataSizePerCommandMB

-MaximumReceivedObjectSizeMB

-ModulesToImport

-Name

-NoServiceRestart

-Path

-ProcessorArchitecture

-PSVersion

-RunAsCredential

-SecurityDescriptorSddl

-SessionTypeOption

-ShowSecurityDescriptorUI

-StartupScript

-ThreadApartmentState

-ThreadOptions

-TransportOption

-UseSharedProcess

-WhatIf

入力

出力

メモ

関連リンク

その他のリソース

例 5: スタートアップスクリプトを使用してセッション構成を登録する