Register-PSSessionConfiguration

構文

Register-PSSessionConfiguration
        [-ProcessorArchitecture <String>]
        [-SessionType <PSSessionType>]
        [-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>]

説明

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

-ApplicationBase

-AssemblyName

-ConfigurationTypeName

-Confirm

-Force

-MaximumReceivedDataSizePerCommandMB

-MaximumReceivedObjectSizeMB

-ModulesToImport

-Name

-NoServiceRestart

-Path

-ProcessorArchitecture

-PSVersion

-RunAsCredential

-SecurityDescriptorSddl

-SessionType

-SessionTypeOption

-ShowSecurityDescriptorUI

-StartupScript

-ThreadApartmentState

-ThreadOptions

-TransportOption

-UseSharedProcess

-WhatIf

入力

None

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

出力

WSManConfigContainerElement

メモ

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

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

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

関連リンク

• Disable-PSSessionConfiguration
• Enable-PSSessionConfiguration
• Get-PSSessionConfiguration
• New-PSSessionConfigurationFile
• New-PSSessionOption
• Register-PSSessionConfiguration
• Set-PSSessionConfiguration
• Test-PSSessionConfigurationFile
• Unregister-PSSessionConfiguration
• WSMan プロバイダー
• about_Session_Configurations
• about_Session_Configuration_Files