Register-PSSessionConfiguration

Register-PSSessionConfiguration
    [-Name] <String>
    [-ProcessorArchitecture <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
    [-Name] <String>
    [-AssemblyName] <String>
    [-ConfigurationTypeName] <String>
    [-ProcessorArchitecture <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
    [-Name] <String>
    -Path <String>
    [-ProcessorArchitecture <String>]
    [-RunAsCredential <PSCredential>]
    [-ThreadApartmentState <ApartmentState>]
    [-ThreadOptions <PSThreadOptions>]
    [-AccessMode <PSSessionConfigurationAccessMode>]
    [-UseSharedProcess]
    [-StartupScript <String>]
    [-MaximumReceivedDataSizePerCommandMB <Double>]
    [-MaximumReceivedObjectSizeMB <Double>]
    [-SecurityDescriptorSddl <String>]
    [-ShowSecurityDescriptorUI]
    [-Force]
    [-NoServiceRestart]
    [-TransportOption <PSTransportOption>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

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

Register-PSSessionConfiguration コマンドレットは、ローカル コンピューターに新しいセッション構成を作成して登録します。 これは、リモート ユーザーのカスタム セッションを作成するために使用できる高度なコマンドレットです。

すべての PowerShell セッション (PSSession) では、セッション構成 (エンドポイントとも呼ばれます) が使用されます。 ユーザーは、コンピューターに接続するセッションを作成するときに、セッション構成を選択するか、PowerShell リモート処理を有効にしたときに登録されている既定のセッション構成を使用できます。 ユーザーは、$PSSessionConfigurationName基本設定変数を設定することもできます。この変数は、現在のセッションで作成されたリモート セッションの既定の構成を指定します。

セッション構成は、リモート セッションの環境を定義します。 構成では、セッションで使用できるコマンドと言語要素を決定できます。また、コンピューターを保護する設定 (セッションが 1 つのオブジェクトまたはコマンドでリモートで受信できるデータの量を制限する設定など) を含めることができます。 セッション構成のセキュリティ記述子によって、セッション構成を使用するアクセス許可を持つユーザーが決まります。

構成の要素を定義するには、新しい構成クラスを実装するアセンブリを使用し、セッションで実行されるスクリプトを使用します。 PowerShell 3.0 以降では、セッション構成ファイルを使用してセッション構成を定義することもできます。

セッション構成の詳細については、about_Session_Configurationsを参照してください。 セッション構成ファイルの詳細については、about_Session_Configuration_Filesを参照してください。

この例では、NewShell セッション構成を登録します。 AssemblyName パラメーターと ApplicationBase パラメーターは、セッション構成のコマンドレットとプロバイダーを指定する MyShell.dll ファイルの場所を指定します。 ConfigurationTypeName パラメーターは、アセンブリから使用する構成クラスを指定します。

$sessionConfiguration = @{
    Name='NewShell'
    ApplicationBase='C:\MyShells\'
    AssemblyName='MyShell.dll'
    ConfigurationTypeName='MyClass'
}
Register-PSSessionConfiguration @sessionConfiguration

この構成を使用するには、「New-PSSession -ConfigurationName NewShell」と入力します。

この例では、MaintenanceShell セッション構成をローカル コンピューターに登録します。 StartupScript パラメーターは、Maintenance.ps1 スクリプトを指定します。

Register-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1

ユーザーが New-PSSession コマンドを使用し、MaintenanceShell 構成を選択すると、Maintenance.ps1 スクリプトが新しいセッションで実行されます。 スクリプトはセッションを構成できます。 これには、モジュールのインポートとセッションの実行ポリシーの設定が含まれます。 スクリプトで終了しないエラーを含むエラーが生成された場合、New-PSSession コマンドは失敗します。

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

$sessionParams 変数は、すべてのパラメーター値を含むハッシュテーブルです。 このハッシュテーブルは、PowerShell スプラッティングを使用してコマンドレットに渡されます。 Register-PSSessionConfiguration コマンドは、SecurityDescriptorSDDL パラメーターを使用して、$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

この例では、MaintenanceShell 構成を登録する方法を示します。 Register-PSSessionConfiguration は、 変数に格納されている $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}

この例では、WithProfile セッション構成を作成して登録します。 StartupScript パラメーターは、セッション構成を使用するすべてのセッションに対して、指定されたスクリプトを実行するように PowerShell に指示します。

Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.ps1

このスクリプトには、ドット ソーシングを使用して、セッションの現在のスコープでユーザーの CurrentUserAllHosts プロファイルを実行する 1 つのコマンドが含まれています。

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

このコマンドレットでは、一般的なパラメーター -Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction、-WarningVariable の各パラメーターがサポートされています。 詳細については、about_CommonParametersを参照してください。

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

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

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

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

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