Register-PSSessionConfiguration

Vytvoří a zaregistruje novou konfiguraci relace.

Syntax

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>]

Description

Tato rutina je dostupná jenom na platformě Windows.

Rutina Register-PSSessionConfiguration vytvoří a zaregistruje novou konfiguraci relace v místním počítači. Jedná se o pokročilou rutinu, kterou můžete použít k vytváření vlastních relací pro vzdálené uživatele.

Každá relace PowerShellu (PSSession) používá konfiguraci relace, označovanou také jako koncový bod. Když uživatelé vytvoří relaci, která se připojí k počítači, můžou vybrat konfiguraci relace nebo použít výchozí konfiguraci relace zaregistrovanou při povolení vzdálené komunikace PowerShellu. Uživatelé mohou také nastavit proměnnou předvoleb $PSSessionConfigurationName, která určuje výchozí konfiguraci vzdálených relací vytvořených v aktuální relaci.

Konfigurace relace definuje prostředí pro vzdálenou relaci. Konfigurace může určit, které příkazy a jazykové prvky jsou v relaci k dispozici, a může obsahovat nastavení, která chrání počítač, například ty, které omezují množství dat, které relace může vzdáleně přijímat v jednom objektu nebo příkazu. Popisovač zabezpečení konfigurace relace určuje, kteří uživatelé mají oprávnění používat konfiguraci relace.

Prvky konfigurace můžete definovat pomocí sestavení, které implementuje novou třídu konfigurace a pomocí skriptu, který se spouští v relaci. Počínaje PowerShellem 3.0 můžete také definovat konfiguraci relace pomocí konfiguračního souboru relace.

Informace o konfiguracích relací najdete v tématu about_Session_Configurations. Informace o konfiguračních souborech relací najdete v tématu about_Session_Configuration_Files.

Příklady

Příklad 1: Registrace konfigurace nové relace ProstředíShell

V tomto příkladu zaregistrujeme konfiguraci relace NewShellu. Parametry AssemblyName a ApplicationBase určují umístění souboru MyShell.dll , který určuje rutiny a zprostředkovatele v konfiguraci relace. Parametr ConfigurationTypeName určuje třídu konfigurace, která se má použít ze sestavení.

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

Chcete-li použít tuto konfiguraci, zadejte New-PSSession -ConfigurationName newshell.

Příklad 2: Registrace konfigurace relace MaintenanceShellu

Tento příklad zaregistruje konfiguraci relace MaintenanceShellu v místním počítači. Parametr StartupScriptu určuje Maintenance.ps1 skript.

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

Když uživatel použije New-PSSession příkaz a vybere konfiguraci MaintenanceShellu , Maintenance.ps1 skript se spustí v nové relaci. Skript může nakonfigurovat relaci. To zahrnuje import modulů a nastavení zásad spouštění pro relaci. Pokud skript vygeneruje nějaké chyby, včetně neukončovaných chyb, New-PSSession příkaz selže.

Příklad 3: Registrace konfigurace relace

Tento příklad zaregistruje konfiguraci relace Správa Shellu.

Proměnná $sessionParams je hashovatelná tabulka obsahující všechny hodnoty parametrů. Tato hashovatelná tabulka se předává rutině pomocí splattingu PowerShellu. Příkaz Register-PSSessionConfiguration pomocí parametru SecurityDescritorSDDL určuje SDDL v hodnotě $sddl proměnné a Parametr MaximumReceivedObjectSizeMB ke zvýšení limitu velikosti objektu. Používá také parametr StartupScript k určení skriptu, který konfiguruje relaci.

$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

Příklad 4: Vrácení elementu kontejneru konfigurace

Tento příklad ukazuje, jak zaregistrovat konfiguraci MaintenanceShellu. Register-PSSessionConfiguration vrátí objekt WSManConfigContainerElement uložený v $s proměnné. Format-List zobrazí všechny vlastnosti vráceného objektu. Vlastnost PSPath ukazuje, že objekt je uložen v adresáři WSMan: jednotka. Get-ChildItem (alias dir) zobrazí položky v cestě WSMan:\LocalHost\PlugIn . Patří sem nová konfigurace MaintenanceShellu a dvě výchozí konfigurace, které jsou součástí PowerShellu.

$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}

Příklad 5: Registrace konfigurace relace pomocí spouštěcího skriptu

V tomto příkladu vytvoříme a zaregistrujeme konfiguraci relace WithProfile . Parametr StartupScriptu přesměruje PowerShell tak, aby spustil zadaný skript pro libovolnou relaci, která používá konfiguraci relace.

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

Skript obsahuje jeden příkaz, který používá dot sourcing ke spuštění profilu CurrentUserAllHosts uživatele v aktuálním oboru relace.

Další informace o profilech najdete v tématu about_Profiles. Další informace o dot sourcingu najdete v tématu about_Scopes.

Parametry

-AccessMode

Povolí a zakáže konfiguraci relace a určí, jestli se dá použít pro vzdálené nebo místní relace v počítači. Tento parametr přijímá tyto hodnoty:

  • Deaktivováno. Zakáže konfiguraci relace. Nelze jej použít pro vzdálený nebo místní přístup k počítači.
  • Místní. Umožňuje uživatelům místního počítače použít konfiguraci relace k vytvoření relace zpětné smyčky na stejném počítači, ale odepře přístup vzdáleným uživatelům.
  • Vzdálené. Umožňuje místním a vzdáleným uživatelům používat konfiguraci relace k vytváření relací a spouštění příkazů na tomto počítači.

Výchozí hodnota je Remote.

Další rutiny mohou později přepsat hodnotu tohoto parametru. Například rutina Enable-PSRemoting umožňuje vzdálený přístup ke všem konfiguracím relací, Enable-PSSessionConfiguration rutina povolí konfigurace relací a rutina Disable-PSRemoting zabrání vzdálenému přístupu ke všem konfiguracím relace.

Tento parametr byl představen v PowerShellu 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

Určuje cestu k souboru sestavení (*.dll), který je zadán v hodnotě parametru AssemblyName . Tento parametr použijte, pokud hodnota parametru AssemblyName neobsahuje cestu. Výchozí je aktuální adresář.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-AssemblyName

Určuje název souboru sestavení (*.dll), ve kterém je definován typ konfigurace. V tomto parametru nebo v hodnotě parametru ApplicationBase můžete zadat cestu .dll.

Tento parametr je vyžadován při zadání parametru ConfigurationTypeName .

Type:String
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-ConfigurationTypeName

Určuje plně kvalifikovaný název typu rozhraní Microsoft .NET Framework, který se používá pro tuto konfiguraci. Typ, který zadáte, musí implementovat System.Management.Automation.Remoting.PSSessionConfiguration třída.

Chcete-li zadat soubor sestavení (*.dll), který implementuje typ konfigurace, zadejte parametry AssemblyName a ApplicationBase .

Vytvoření typu umožňuje řídit více aspektů konfigurace relace, jako je zveřejnění nebo skrytí určitých parametrů rutin nebo nastavení omezení velikosti dat a velikosti objektu, které uživatelé nemohou přepsat.

Pokud tento parametr vynecháte, použije se pro konfiguraci relace třída DefaultRemotePowerShellConfiguration .

Type:String
Position:2
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Confirm

Před spuštěním rutiny zobrazí výzvu k potvrzení.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Force

Potlačí všechny výzvy uživatele a restartuje službu WinRM bez výzvy. Restartováním služby se změna konfigurace projeví.

Pokud chcete zabránit restartování a potlačit výzvu k restartování, zadejte parametr NoServiceRestart .

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaximumReceivedDataSizePerCommandMB

Určuje limit pro množství dat, která lze odeslat do tohoto počítače v libovolném vzdáleném příkazu. Zadejte velikost dat v megabajtech (MB). Výchozí hodnota je 50 MB.

Pokud je omezení velikosti dat definováno v typu konfigurace zadaném v parametru ConfigurationTypeName , použije se limit typu konfigurace a hodnota tohoto parametru se ignoruje.

Type:Nullable<T>[Double]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaximumReceivedObjectSizeMB

Určuje limit pro množství dat, která lze odeslat do tohoto počítače v libovolném objektu. Zadejte velikost dat v megabajtech. Výchozí hodnota je 10 MB.

Pokud je limit velikosti objektu definován v typu konfigurace, který je zadán v parametru ConfigurationTypeName , použije se limit typu konfigurace a hodnota tohoto parametru bude ignorována.

Type:Nullable<T>[Double]
Position:Named
Default value:10
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ModulesToImport

Určuje moduly, které se automaticky importují do relací, které používají konfiguraci relace.

Ve výchozím nastavení se do relací importuje jenom Microsoft.PowerShell.Core . Pokud nejsou rutiny vyloučené, můžete do relace přidat Import-Module moduly.

Moduly zadané v této hodnotě parametru se importují kromě modulů určených parametrem SessionType a modulů uvedených v klíči ModulesToImport v konfiguračním souboru relace (New-PSSessionConfigurationFile). Nastavení v konfiguračním souboru relace ale můžou skrýt příkazy exportované moduly nebo zabránit uživatelům v jejich používání.

Tento parametr byl představen v PowerShellu 3.0.

Type:Object[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Name

Určuje název konfigurace relace. Tento parametr je povinný.

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-NoServiceRestart

Nerestartuje službu WinRM a potlačí výzvu k restartování služby.

Při spuštění Register-PSSessionConfiguration příkazu se ve výchozím nastavení zobrazí výzva k restartování služby WinRM , aby se nová konfigurace relace projevila. Dokud se služba WinRM nerestartuje, nová konfigurace relace není platná.

Pokud chcete službu WinRM restartovat bez výzvy, zadejte parametr Force. Pokud chcete službu WinRM restartovat ručně, použijte tuto rutinuRestart-Service.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Path

Určuje cestu a název souboru konfiguračního souboru relace (.pssc), například soubor vytvořený uživatelem New-PSSessionConfigurationFile. Pokud tuto cestu vynecháte, výchozí je aktuální adresář.

Tento parametr byl představen v PowerShellu 3.0.

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-ProcessorArchitecture

Určuje, jestli je v relacích, které používají tuto konfiguraci relace, spuštěna 32bitová nebo 64bitová verze procesu PowerShellu. Přijatelné hodnoty pro tento parametr jsou: x86 (32bitová verze) a AMD64 (64bitová verze). Výchozí hodnota je určena architekturou procesoru počítače, který hostuje konfiguraci relace.

Tento parametr můžete použít k vytvoření 32bitové relace na 64bitovém počítači. Pokusy o vytvoření 64bitového procesu na 32bitovém počítači selžou.

Type:String
Aliases:PA
Accepted values:x86, amd64
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-PSVersion

Určuje verzi PowerShellu v relacích, které používají tuto konfiguraci relace.

Hodnota tohoto parametru má přednost před hodnotou klíče PowerShellVersion v konfiguračním souboru relace.

Tento parametr byl představen v PowerShellu 3.0.

Type:Version
Aliases:PowerShellVersion
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RunAsCredential

Určuje přihlašovací údaje pro příkazy v relaci. Ve výchozím nastavení se příkazy spouštějí s oprávněními aktuálního uživatele.

Tento parametr byl představen v PowerShellu 3.0.

Type:PSCredential
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SecurityDescriptorSddl

Určuje řetězec SDDL (Security Descriptor Definition Language) pro konfiguraci.

Tento řetězec určuje oprávnění potřebná k použití nové konfigurace relace. Pokud chcete v relaci použít konfiguraci relace, musí mít uživatelé alespoň oprávnění Spustit (Vyvolat) pro konfiguraci.

Pokud je popisovač zabezpečení složitý, zvažte použití parametru ShowSecurityDescriptorUI místo tohoto parametru. Oba parametry nelze použít ve stejném příkazu.

Pokud tento parametr vynecháte, použije se pro tuto konfiguraci kořenový SDDL pro službu WinRM . Pokud chcete zobrazit nebo změnit kořenový SDDL, použijte zprostředkovatele WSMan. Příklad: Get-Item wsman:\localhost\service\rootSDDL. Další informace o zprostředkovateli WSMan zadejte Get-Help wsman.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SessionTypeOption

Určuje možnosti specifické pro typ konfigurace relace. Zadejte objekt možností typu relace, například OBJEKT PSWorkflowExecutionOption , který rutina New-PSWorkflowExecutionOption vrátí.

Možnosti relací, které používají konfiguraci relace, jsou určeny hodnotami možností relace a možnostmi konfigurace relace. Pokud nejsou zadané, mají možnosti nastavené v relaci, například pomocí New-PSSessionOption rutiny, přednost před možnostmi nastavenými v konfiguraci relace. Hodnoty možností relace však nesmí překročit maximální hodnoty nastavené v konfiguraci relace.

Tento parametr byl představen v PowerShellu 3.0.

Type:PSSessionTypeOption
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ShowSecurityDescriptorUI

Označuje, že tato rutina zobrazí seznam vlastností, který vám pomůže vytvořit SDDL pro konfiguraci relace. Seznam vlastností se zobrazí po zadání Register-PSSessionConfiguration příkazu a potom restartujte službu WinRM .

Při nastavování oprávnění pro konfiguraci nezapomeňte, že uživatelé musí mít alespoň oprávnění Spustit (Vyvolat), aby mohli v relaci používat konfiguraci relace.

Nelze použít parametr SecurityDescriptorSDDL a tento parametr ve stejném příkazu.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-StartupScript

Určuje plně kvalifikovanou cestu skriptu PowerShellu. Zadaný skript se spustí v nové relaci, která používá konfiguraci relace.

Skript můžete použít k další konfiguraci relace. Pokud skript vygeneruje chybu, a to i neukončující chybu, relace se nevytvořila a New-PSSession příkaz selže.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ThreadApartmentState

Určuje stav apartmánu modulu threadingu, který se má použít. Přijatelné hodnoty jsou:

  • Neznámý
  • MTA
  • STA
Type:ApartmentState
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ThreadOptions

Určuje, jak se vlákna vytvářejí a používají při spuštění příkazu v relaci. Tento parametr přijímá tyto hodnoty:

  • Výchozí
  • Znovu použítThread
  • UseCurrentThread
  • UseNewThread

Výchozí hodnota je UseCurrentThread.

Další informace naleznete v tématu PSThreadOptions Výčtu.

Type:PSThreadOptions
Accepted values:Default, UseNewThread, ReuseThread, UseCurrentThread
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-TransportOption

Určuje možnost přenosu.

Tento parametr byl představen v PowerShellu 3.0.

Type:PSTransportOption
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-UseSharedProcess

K hostování všech relací spuštěných stejným uživatelem použijte pouze jeden proces a použijte stejnou konfiguraci relace. Ve výchozím nastavení se každá relace hostuje ve vlastním procesu.

Tento parametr byl představen v PowerShellu 3.0.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WhatIf

Zobrazuje, co by se stalo při spuštění rutiny. Rutina není spuštěna.

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Vstupy

None

Do této rutiny nemůžete roušit objekty.

Výstupy

WSManConfigContainerElement

Poznámky

Tato rutina je dostupná jenom na platformách Windows.

Chcete-li spustit tuto rutinu , musíte spustit PowerShell pomocí možnosti Spustit jako správce .

Tato rutina vygeneruje xml, který představuje konfiguraci modulu plug-in Ws-Management (Web Services for Management) a odešle xml do služby WS-Management, která zaregistruje modul plug-in v místním počítači (New-Item wsman:\localhost\plugin).

Vlastnosti objektu konfigurace relace se liší podle možností nastavených pro konfiguraci relace a hodnot těchto možností. Konfigurace relací, které používají konfigurační soubor relace, mají také další vlastnosti.