Register-PSSessionConfiguration
Vytvoří a zaregistruje novou konfiguraci relace.
Syntaxe
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 AdminShellu.
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. Nedá se 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.
Typ: | PSSessionConfigurationAccessMode |
Přípustné hodnoty: | Disabled, Local, Remote |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | False |
-ApplicationBase
Určuje cestu k souboru sestavení (*.dll
), který je zadaný v hodnotě parametru AssemblyName . Tento parametr použijte, pokud hodnota parametru AssemblyName neobsahuje cestu. Výchozí je aktuální adresář.
Typ: | String |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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 .
Typ: | String |
Position: | 1 |
Default value: | None |
Vyžadováno: | True |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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.
Pokud chcete 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 .
Typ: | String |
Position: | 2 |
Default value: | None |
Vyžadováno: | True |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | False |
-Confirm
Před spuštěním rutiny zobrazí výzvu k potvrzení.
Typ: | SwitchParameter |
Aliasy: | cf |
Position: | Named |
Default value: | False |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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 .
Typ: | SwitchParameter |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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 limit velikosti dat definován v konfiguračním typu zadaném v parametru ConfigurationTypeName , použije se limit typu konfigurace a hodnota tohoto parametru se ignoruje.
Typ: | Nullable<T>[Double] |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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 zadaný v parametru ConfigurationTypeName , použije se limit typu konfigurace a hodnota tohoto parametru se ignoruje.
Typ: | Nullable<T>[Double] |
Position: | Named |
Default value: | 10 |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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.
Typ: | Object[] |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | False |
-Name
Určuje název konfigurace relace. Tento parametr je povinný.
Typ: | String |
Position: | 0 |
Default value: | None |
Vyžadováno: | True |
Přijmout vstup kanálu: | True |
Přijmout zástupné znaky: | False |
-NoServiceRestart
Účelem tohoto parametru je zabránit restartování služby WinRM . Tato funkce ještě není implementována.
Tato funkce byla implementována v PowerShellu 7.5.0-preview.4.
Typ: | SwitchParameter |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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.
Typ: | String |
Position: | Named |
Default value: | None |
Vyžadováno: | True |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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.
Typ: | String |
Aliasy: | PA |
Přípustné hodnoty: | x86, amd64 |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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.
Typ: | Version |
Aliasy: | PowerShellVersion |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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.
Typ: | PSCredential |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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 nemůžete 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
.
Typ: | String |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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 ale nemůžou překročit maximální hodnoty nastavené v konfiguraci relace.
Tento parametr byl představen v PowerShellu 3.0.
Typ: | PSSessionTypeOption |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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.
Typ: | SwitchParameter |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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.
Typ: | String |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | False |
-ThreadApartmentState
Určuje stav apartmánu modulu threadingu, který se má použít. Přijatelné hodnoty jsou:
- Neznámý
- MTA
- STA
Typ: | ApartmentState |
Přípustné hodnoty: | STA, MTA, Unknown |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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.
Typ: | PSThreadOptions |
Přípustné hodnoty: | Default, UseNewThread, ReuseThread, UseCurrentThread |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | False |
-TransportOption
Určuje možnost přenosu.
Tento parametr byl představen v PowerShellu 3.0.
Typ: | PSTransportOption |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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.
Typ: | SwitchParameter |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | False |
-WhatIf
Zobrazuje, co by se stalo při spuštění rutiny. Rutina se nespustí.
Typ: | SwitchParameter |
Aliasy: | wi |
Position: | Named |
Default value: | False |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | False |
Vstupy
None
Do této rutiny nemůžete roušit objekty.
Výstupy
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.