Register-PSSessionConfiguration

[アーティクル]
10/30/2009

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

構文

Register-PSSessionConfiguration [-AssemblyName] <string> [-ConfigurationTypeName] <string> [-ApplicationBase <string>] [-Name] <string> [-Force] [-MaximumReceivedDataSizePerCommandMB <double>] [-MaximumReceivedObjectSizeMB <double>] [-NoServiceRestart] [-ProcessorArchitecture <string>] [-SecurityDescriptorSDDL <string>] [-ShowSecurityDescriptorUI] [-StartupScript <string>] [-ThreadApartmentState {<STA> | <MTA> | <Unknown>}] [-ThreadOptions {<Default> | <UseNewThread> | <ReuseThread> | <UseCurrentThread>}] [-Confirm] [-WhatIf] [<CommonParameters>]

説明

Register-PSSessionConfiguration コマンドレットは、ローカルコンピューター上に新しいセッション構成を作成して登録します。これは、システム管理者がユーザーの代わりにカスタマイズされたセッション構成を管理するために使用する高度なコマンドレットです。

すべての Windows PowerShell リモートセッションは、セッション構成を使用します。コンピューターに接続するセッションを作成する際には、構成を選択することも、Windows PowerShell リモート処理を有効にしたときに登録される既定の構成を使用することもできます。また、現在のセッションで作成されたセッションの既定の構成を指定する $PSSessionConfigurationName 設定変数も設定できます。

セッション構成で構成するのは、セッションの環境です。構成は、新しい構成クラスを実装するアセンブリを使用すること、およびセッションで実行されるスクリプトを使用することによって定義できます。構成では、セッションで使用できるコマンドを決定できます。構成には、コンピューターを保護するための設定 (セッションで単一のオブジェクトやコマンドを通じてリモートで受信できるデータの量を制限する設定など) を含めることができます。さらに、構成を使用するために必要なアクセス許可を指定するセキュリティ記述子を指定することもできます。

パラメーター

-ApplicationBase <string>

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

必須	false
位置	named
既定値	Current directory
パイプライン入力を許可する	false
ワイルドカード文字を許可する	false

-AssemblyName <string>

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

このパラメーターは、ConfigurationTypeName パラメーターが指定されているときに必須です。

必須	true
位置	2
既定値	なし
パイプライン入力を許可する	false
ワイルドカード文字を許可する	false

-ConfigurationTypeName <string>

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

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

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

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

必須	true
位置	3
既定値	System.Management.Automation.Remoting.PSSessionConfiguration
パイプライン入力を許可する	false
ワイルドカード文字を許可する	false

-Force

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

再起動せず、再起動プロンプトが表示されないようにするには、NoServiceRestart パラメーターを使用します。

必須	false
位置	named
既定値
パイプライン入力を許可する	false
ワイルドカード文字を許可する	false

-MaximumReceivedDataSizePerCommandMB <double>

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

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

必須	false
位置	named
既定値	50
パイプライン入力を許可する	false
ワイルドカード文字を許可する	false

-MaximumReceivedObjectSizeMB <double>

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

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

必須	false
位置	named
既定値	10
パイプライン入力を許可する	false
ワイルドカード文字を許可する	false

-Name <string>

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

必須	true
位置	1
既定値	なし
パイプライン入力を許可する	false
ワイルドカード文字を許可する	false

-NoServiceRestart

WinRM サービスを再起動せず、サービスの再起動を確認するメッセージを非表示にします。

既定では、Register-PSSessionConfiguration コマンドを入力すると、新しいセッション構成を適用するために WinRM サービスを再起動するよう求められます。新しいセッション構成は、WinRM サービスを再起動するまで有効になりません。

確認メッセージを表示しないで WinRM サービスを再起動するには、Force パラメーターを使用します。WinRM サービスを手動で再起動するには、Restart-Service コマンドレットを使用します。

必須	false
位置	named
既定値	False
パイプライン入力を許可する	false
ワイルドカード文字を許可する	false

-ProcessorArchitecture <string>

構成のプロセッサアーキテクチャを指定します。この値は、構成が使用されたときに Windows PowerShell をホストするプロセッサの 32 ビット版を開始するか 64 ビット版を開始するかを決定します。有効な値は、x86、AMD64、および IA64 です。

既定値は、セッション構成をホストするコンピューターのプロセッサアーキテクチャによって決定されます。

必須	false
位置	named
既定値	The processor architecture of the host computer.
パイプライン入力を許可する	false
ワイルドカード文字を許可する	false

-SecurityDescriptorSDDL <string>

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

この文字列は、新しいセッション構成を使用するために必要なアクセス許可を定義します。セッションでセッション構成を使用するには、少なくとも構成に対する "実行 (Invoke)" アクセス許可が必要です。

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

このパラメーターを省略した場合、この構成で WinRM サービスのルート SDDL が使用されます。ルート SDDL を表示または変更するには、WS-Management プロバイダーを使用します。たとえば、「get-item wsman:\localhost\service\rootSDDL」と入力します。WS-Management プロバイダーの詳細については、「get-help wsman」と入力してください。

必須	false
位置	named
既定値	The value of the root SDDL
パイプライン入力を許可する	false
ワイルドカード文字を許可する	false

-ShowSecurityDescriptorUI

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

構成のアクセス許可を設定する場合、セッションでセッション構成を使用するには少なくとも "実行 (Invoke)" アクセス許可が必要であることに注意します。

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

必須	false
位置	named
既定値
パイプライン入力を許可する	false
ワイルドカード文字を許可する	false

-StartupScript <string>

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

スクリプトを使用して、セッションの詳細な構成を行うことができます。スクリプトでエラー (未終了エラーを含む) が発生した場合セッションは作成されず、ユーザーの New-PSSession コマンドは失敗します。

必須	false
位置	named
既定値
パイプライン入力を許可する	false
ワイルドカード文字を許可する	false

-ThreadApartmentState <ApartmentState>

セッション内のスレッドのアパートメント状態を決定します。有効な値は、STA、MTA、および Unknown です。既定値は Unknown です。

必須	false
位置	named
既定値	Unknown
パイプライン入力を許可する	false
ワイルドカード文字を許可する	false

-ThreadOptions <PSThreadOptions>

セッションでコマンドが実行されたときのスレッドの作成方法および使用方法を定義します。有効な値は、Default、ReuseThread、UseCurrentThread、および UseNewThread です。既定値は UseCurrentThread です。

必須	false
位置	named
既定値	UseCurrentThread
パイプライン入力を許可する	false
ワイルドカード文字を許可する	false

-Confirm

コマンドを実行する前に確認メッセージを表示します。

必須	false
位置	named
既定値
パイプライン入力を許可する	false
ワイルドカード文字を許可する	false

-WhatIf

実際にコマンドを実行せずに、コマンドを実行すると何が起きるかを出力します。

必須	false
位置	named
既定値
パイプライン入力を許可する	false
ワイルドカード文字を許可する	false

<CommonParameters>

このコマンドレットは、次の共通パラメーターをサポートします: -Verbose、-Debug、-ErrorAction、-ErrorVariable、-OutBuffer、および -OutVariable。詳細については、次を参照してください: about_Commonparameters.

入力と出力

入力値の型は、コマンドレットへのパイプが可能なオブジェクトの型です。戻り値の型は、コマンドレットによって返されるオブジェクトの型です。

入力

None

パイプを使用してこのコマンドレットに入力を渡すことはできません。

出力

Microsoft.WSMan.Management.WSManConfigContainerElement

注

Windows Vista、Windows Server 2008、およびそれ以降のバージョンの Windows でこのコマンドレットを実行するには、Windows PowerShell を起動する際に [管理者として実行] を指定する必要があります。

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

例 1

C:\PS>register-pssessionConfiguration -name NewShell -applicationBase c:\MyShells\ -assemblyName MyShell.dll -configurationTypeName MyClass

説明
-----------
このコマンドは、NewShell セッション構成を登録します。このコマンドは、ApplicationName および ApplicationBase パラメーターを使用して、セッション構成のコマンドレッドおよびプロバイダーを指定する MyShell.dll ファイルの場所を指定します。また、セッションの詳細を構成する新しいクラスを指定する ConfigurationTypeName パラメーターも使用します。

この構成を使用するには、「new-pssession -configurationname newshell」と入力します。

例 2

C:\PS>register-pssessionConfiguration -name MaintenanceShell -startupScript c:\ps-test\Maintenance.ps1

説明
-----------
このコマンドは、MaintenanceShell 構成をローカル コンピューターに登録します。このコマンドは、StartupScript パラメーターを使用して Maintenance.ps1 スクリプトを指定します。

ユーザーが New-PSSession コマンドを使用して MaintenanceShell 構成を選択すると、新しいセッションで Maintenance.ps1 スクリプトが実行されます。スクリプトでは、モジュールのインポート、Windows PowerShell スナップインの追加、およびセッションの実行ポリシーの設定を始めとするセッション構成を行うことができます。スクリプトでエラー (未終了エラーを含む) が発生した場合、New-PSSession コマンドは失敗します。

例 3

C:\PS>$sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FA;SA;GWGX;;WD)"

C:\PS> register-pssessionconfiguration -name AdminShell -securityDescriptorSDDL $sddl -maximumReceivedObjectSizeMB 20 -startupScript c:\scripts\AdminShell.ps1

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

最初のコマンドは、カスタム SDDL を $sddl 変数に保存します。

2 番目のコマンドは、新しいシェルを登録します。コマンドは、SecurityDescritorSDDL パラメーターを使用して $sddl 変数の値の SDDL を指定し、MaximumReceivedObjectSizeMB パラメーターを使用して オブジェクトのサイズ制限を増加します。また、セッションを構成するスクリプトを指定する StartupScript パラメーターも使用します。

SecurityDescriptorSDDL パラメーターを使用する代わりに、ShowSecurityDescriptorUI パラメーターを使用することができます。このパラメーターにより、セッション構成のアクセス許可を設定するために使用できるプロパティ シートが表示されます。プロパティ シートで [OK] をクリックすると、セッション構成の SDDL が生成されます。

例 4

C:\PS>$s = register-pssessionConfiguration -name MaintenanceShell -startupScript c:\ps-test\Maintenance.ps1

C:\PS> $s

   WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin

Name                      Type                 Keys
----                      ----                 ----
MaintenanceShell          Container            {Name=MaintenanceShell}


C:\PS> $s.getType().fullname
TypeName: Microsoft.WSMan.Management.WSManConfigContainerElement


C:\PS> $s | format-list -property *

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


C:\PS> dir wsman:\localhost\plugin

Name                      Type                 Keys
----                      ----                 ----
MaintenanceShell          Container            {Name=MaintenanceShell}
microsoft.powershell      Container            {Name=microsoft.powershell}
microsoft.powershell32    Container            {Name=microsoft.powershell32}

説明
-----------
この例は、Register-PSSessionConfiguration コマンドが WSManConfigContainerElement を返すことを示します。また、WSMan: ドライブでコンテナー要素を見つける方法も示します。

最初のコマンドは Register-PSSessionConfiguration コマンドレットを使用して MaintenanceShell 構成を登録します。このコマンドは、コマンドレットが返すオブジェクトを $s 変数に保存します。

2 番目のコマンドは、$s 変数の内容を表示します。

3 番目のコマンドは、GetType メソッドおよびその FullName プロパティを使用して、Register-PSSessionConfiguration が返すオブジェクトの型名を表示します。

4 番目のコマンドは、Format-List コマンドレットを使用して、Register-PSSessionConfiguration が返すオブジェクトのすべてのプロパティを一覧表示します。PSPath プロパティは、オブジェクトが WSMan: ドライブのディレクトリに保存されていることを示します。

5 番目のコマンドは、Get-ChildItem コマンドレットを使用して、WSMan:\LocalHost\PlugIn パスにある項目を表示します。これらの項目には、新しい MaintenanceShell 構成および Windows PowerShell に含まれる 2 つの既定の構成が含まれます。

例 5

C:\PS>register-pssessionconfiguration -name WithProfile -startupScript add-profile.ps1

# Add-Profile.ps1

. c:\users\admin01\documents\windowspowershell\profile.ps1

説明
-----------
このコマンドは、WithProfile セッション構成を作成してローカル コンピューターに登録します。このコマンドは、StartupScript パラメーターを使用することにより、セッション構成が使用されるすべてのセッションで、指定したスクリプトを実行するよう Windows PowerShell に指示します。

指定したスクリプトの内容である Add-Profile.ps1 も表示されます。スクリプトには、セッションの現在のスコープでユーザーの CurrentUserAllHosts プロファイルを実行するドット ソースを使用する単一のコマンドが含まれます。

プロファイルの詳細については、「about_Profiles」を参照してください。ドット ソースの詳細については、「about_Scopes」を参照してください。

次の方法で共有