Register-PSSessionConfiguration
Skapar och registrerar en ny sessionskonfiguration.
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
Den här cmdleten är endast tillgänglig på Windows-plattformen.
Cmdleten Register-PSSessionConfiguration
skapar och registrerar en ny sessionskonfiguration på den lokala datorn. Det här är en avancerad cmdlet som du kan använda för att skapa anpassade sessioner för fjärranvändare.
Varje PowerShell-session (PSSession) använder en sessionskonfiguration, även kallad en slutpunkt. När användarna skapar en session som ansluter till datorn kan de välja en sessionskonfiguration eller använda standardkonfigurationen för sessioner som registreras när du aktiverar PowerShell-fjärrkommunikation. Användare kan också ange $PSSessionConfigurationName inställningsvariabel, som anger en standardkonfiguration för fjärrsessioner som skapats i den aktuella sessionen.
Sessionskonfigurationen definierar miljön för fjärrsessionen. Konfigurationen kan avgöra vilka kommandon och språkelement som är tillgängliga i sessionen och kan innehålla inställningar som skyddar datorn, till exempel de som begränsar mängden data som sessionen kan ta emot via fjärranslutning i ett enda objekt eller kommando. Säkerhetsbeskrivningen för sessionskonfigurationen avgör vilka användare som har behörighet att använda sessionskonfigurationen.
Du kan definiera konfigurationselementen med hjälp av en sammansättning som implementerar en ny konfigurationsklass och med hjälp av ett skript som körs i sessionen. Från och med PowerShell 3.0 kan du också använda en sessionskonfigurationsfil för att definiera sessionskonfigurationen.
Information om sessionskonfigurationer finns i about_Session_Configurations. Information om sessionskonfigurationsfiler finns i about_Session_Configuration_Files.
Exempel
Exempel 1: Registrera en Konfiguration av NewShell-sessioner
I det här exemplet registrerar vi konfigurationen för NewShell-sessionen . Parametrarna AssemblyName och ApplicationBase anger platsen för MyShell.dll-filen, som anger cmdletar och providers i sessionskonfigurationen. Parametern ConfigurationTypeName anger vilken konfigurationsklass som ska användas från sammansättningen.
$sessionConfiguration = @{
Name='NewShell'
ApplicationBase='c:\MyShells\'
AssemblyName='MyShell.dll'
ConfigurationTypeName='MyClass'
}
Register-PSSessionConfiguration @sessionConfiguration
Om du vill använda den här konfigurationen skriver du New-PSSession -ConfigurationName newshell
.
Exempel 2: Registrera en MaintenanceShell-sessionskonfiguration
I det här exemplet registreras maintenanceShell-sessionskonfigurationen på den lokala datorn. Parametern StartupScript anger skriptet Maintenance.ps1
.
Register-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1
När en användare använder ett New-PSSession
kommando och väljer MaintenanceShell-konfigurationen körs skriptet Maintenance.ps1
i den nya sessionen. Skriptet kan konfigurera sessionen. Detta omfattar import av moduler och inställning av körningsprincipen för sessionen. Om skriptet genererar några fel, inklusive icke-avslutande fel, New-PSSession
misslyckas kommandot.
Exempel 3: Registrera en sessionskonfiguration
I det här exemplet registreras AdminShell-sessionskonfigurationen .
Variabeln $sessionParams
är en hashtable som innehåller alla parametervärden. Den här hashtabellen skickas till cmdleten med hjälp av PowerShell-splatting. Kommandot Register-PSSessionConfiguration
använder parametern SecurityDescritorSDDL för att ange SDDL i värdet för variabeln $sddl
och parametern MaximumReceivedObjectSizeMB för att öka objektets storleksgräns. Den använder också parametern StartupScript för att ange ett skript som konfigurerar sessionen.
$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
Exempel 4: Returnera ett konfigurationscontainerelement
Det här exemplet visar hur du registrerar MaintenanceShell-konfigurationen .
Register-PSSessionConfiguration
returnerar ett WSManConfigContainerElement-objekt som lagras i variabeln $s
. Format-List
visar alla egenskaper för det returnerade objektet. PsPath-egenskapen visar att objektet lagras i en katalog på WSMan:-enheten. Get-ChildItem
(alias dir
) visar objekten WSMan:\LocalHost\PlugIn
i sökvägen. Dessa inkluderar den nya MaintenanceShell-konfigurationen och de två standardkonfigurationerna som medföljer PowerShell.
$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}
Exempel 5: Registrera en sessionskonfiguration med ett startskript
I det här exemplet skapar och registrerar vi konfigurationen av WithProfile-sessionen . Parametern StartupScript instruerar PowerShell att köra det angivna skriptet för alla sessioner som använder sessionskonfigurationen.
Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.ps1
Skriptet innehåller ett enda kommando som använder punktkällor för att köra användarens CurrentUserAllHosts-profil i sessionens aktuella omfång.
Mer information om profiler finns i about_Profiles. Mer information om punktkällor finns i about_Scopes.
Parametrar
-AccessMode
Aktiverar och inaktiverar sessionskonfigurationen och avgör om den kan användas för fjärrsessioner eller lokala sessioner på datorn. De acceptabla värdena för den här parametern är:
- Inaktiverat. Inaktiverar sessionskonfigurationen. Den kan inte användas för fjärråtkomst eller lokal åtkomst till datorn.
- Lokal. Tillåter användare av den lokala datorn att använda sessionskonfigurationen för att skapa en lokal loopback-session på samma dator, men nekar åtkomst till fjärranvändare.
- Avlägsen. Gör att lokala och fjärranslutna användare kan använda sessionskonfigurationen för att skapa sessioner och köra kommandon på den här datorn.
Standardvärdet är Fjärr.
Andra cmdletar kan åsidosätta värdet för den här parametern senare. Till exempel tillåter cmdleten Enable-PSRemoting
fjärråtkomst till alla sessionskonfigurationer, cmdleten Enable-PSSessionConfiguration
aktiverar sessionskonfigurationer och cmdleten Disable-PSRemoting
förhindrar fjärråtkomst till alla sessionskonfigurationer.
Den här parametern introducerades i PowerShell 3.0.
Typ: | PSSessionConfigurationAccessMode |
Godkända värden: | Disabled, Local, Remote |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-ApplicationBase
Anger sökvägen till sammansättningsfilen (*.dll
) som anges i värdet för parametern AssemblyName . Använd den här parametern när värdet för parametern AssemblyName inte innehåller någon sökväg. Standardvärdet är den aktuella katalogen.
Typ: | String |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-AssemblyName
Anger namnet på en sammansättningsfil (*.dll) där konfigurationstypen har definierats. Du kan ange sökvägen för .dll i den här parametern eller i värdet för parametern ApplicationBase .
Den här parametern krävs när du anger parametern ConfigurationTypeName .
Typ: | String |
Position: | 1 |
Standardvärde: | None |
Obligatorisk: | True |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-ConfigurationTypeName
Anger det fullständigt kvalificerade namnet på den Microsoft .NET Framework-typ som används för den här konfigurationen. Den typ som du anger måste implementera klassen System.Management.Automation.Remoting.PSSessionConfiguration .
Om du vill ange sammansättningsfilen (*.dll
) som implementerar konfigurationstypen anger du parametrarna AssemblyName och ApplicationBase .
Genom att skapa en typ kan du styra fler aspekter av sessionskonfigurationen, till exempel att exponera eller dölja vissa parametrar för cmdletar, eller ange datastorlek och objektstorleksgränser som användarna inte kan åsidosätta.
Om du utelämnar den här parametern används klassen DefaultRemotePowerShellConfiguration för sessionskonfigurationen.
Typ: | String |
Position: | 2 |
Standardvärde: | None |
Obligatorisk: | True |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-Confirm
Uppmanar dig att bekräfta innan du kör cmdleten.
Typ: | SwitchParameter |
Alias: | cf |
Position: | Named |
Standardvärde: | False |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-Force
Undertrycker alla användarprompter och startar om WinRM-tjänsten utan att fråga. Om du startar om tjänsten blir konfigurationsändringen effektiv.
Om du vill förhindra en omstart och ignorera omstartsprompten anger du parametern NoServiceRestart .
Typ: | SwitchParameter |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-MaximumReceivedDataSizePerCommandMB
Anger en gräns för hur mycket data som kan skickas till den här datorn i ett enda fjärrkommando. Ange datastorleken i megabyte (MB). Standardvärdet är 50 MB.
Om en datastorleksgräns definieras i den konfigurationstyp som anges i parametern ConfigurationTypeName används gränsen i konfigurationstypen och värdet för den här parametern ignoreras.
Typ: | Nullable<T>[Double] |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-MaximumReceivedObjectSizeMB
Anger en gräns för hur mycket data som kan skickas till den här datorn i ett enskilt objekt. Ange datastorleken i megabyte. Standardvärdet är 10 MB.
Om en storleksgräns för objekt definieras i den konfigurationstyp som anges i parametern ConfigurationTypeName används gränsen i konfigurationstypen och värdet för den här parametern ignoreras.
Typ: | Nullable<T>[Double] |
Position: | Named |
Standardvärde: | 10 |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-ModulesToImport
Anger de moduler som automatiskt importeras till sessioner som använder sessionskonfigurationen.
Som standard importeras endast Microsoft.PowerShell.Core till sessioner. Om inte cmdletarna undantas kan du använda Import-Module
för att lägga till moduler i sessionen.
Modulerna som anges i det här parametervärdet importeras utöver moduler som anges av parametern SessionType och de som anges i nyckeln ModulesToImport i sessionskonfigurationsfilen (New-PSSessionConfigurationFile
). Inställningarna i sessionskonfigurationsfilen kan dock dölja kommandon som exporteras av moduler eller hindra användare från att använda dem.
Den här parametern introducerades i PowerShell 3.0.
Typ: | Object[] |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-Name
Anger ett namn för sessionskonfigurationen. Den här parametern krävs.
Typ: | String |
Position: | 0 |
Standardvärde: | None |
Obligatorisk: | True |
Godkänn pipeline-indata: | True |
Godkänn jokertecken: | False |
-NoServiceRestart
Avsikten med den här parametern är att förhindra omstarten av WinRM-tjänsten . Den här funktionen har inte implementerats än.
Den här funktionen implementerades i PowerShell 7.5.0-preview.4.
Typ: | SwitchParameter |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-Path
Anger sökvägen och filnamnet för en sessionskonfigurationsfil (.pssc), till exempel en som skapats av New-PSSessionConfigurationFile
. Om du utelämnar sökvägen är standardvärdet den aktuella katalogen.
Den här parametern introducerades i PowerShell 3.0.
Typ: | String |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | True |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-ProcessorArchitecture
Avgör om en 32-bitars eller 64-bitars version av PowerShell-processen startas i sessioner som använder den här sessionskonfigurationen. De godtagbara värdena för den här parametern är: x86 (32-bitars) och AMD64 (64-bitars). Standardvärdet bestäms av processorarkitekturen på den dator som är värd för sessionskonfigurationen.
Du kan använda den här parametern för att skapa en 32-bitars session på en 64-bitars dator. Försök att skapa en 64-bitarsprocess på en 32-bitars dator misslyckas.
Typ: | String |
Alias: | PA |
Godkända värden: | x86, amd64 |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-PSVersion
Anger versionen av PowerShell i sessioner som använder den här sessionskonfigurationen.
Värdet för den här parametern har företräde framför värdet för PowerShellVersion-nyckeln i sessionskonfigurationsfilen.
Den här parametern introducerades i PowerShell 3.0.
Typ: | Version |
Alias: | PowerShellVersion |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-RunAsCredential
Anger autentiseringsuppgifter för kommandon i sessionen. Som standard körs kommandon med den aktuella användarens behörigheter.
Den här parametern introducerades i PowerShell 3.0.
Typ: | PSCredential |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-SecurityDescriptorSddl
Anger en SDDL-sträng (Security Descriptor Definition Language) för konfigurationen.
Den här strängen avgör vilka behörigheter som krävs för att använda den nya sessionskonfigurationen. Om du vill använda en sessionskonfiguration i en session måste användarna ha minst behörigheten Kör (anropa) för konfigurationen.
Om säkerhetsbeskrivningen är komplex bör du överväga att använda parametern ShowSecurityDescriptorUI i stället för den här parametern. Du kan inte använda båda parametrarna i samma kommando.
Om du utelämnar den här parametern används rot-SDDL för WinRM-tjänsten för den här konfigurationen.
Om du vill visa eller ändra rot-SDDL använder du WSMan-providern. Till exempel Get-Item wsman:\localhost\service\rootSDDL
. Om du vill ha mer information om WSMan-providern skriver du Get-Help wsman
.
Typ: | String |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-SessionTypeOption
Anger typspecifika alternativ för sessionskonfigurationen. Ange ett alternativobjekt för sessionstyp, till exempel det PSWorkflowExecutionOption-objekt som cmdleten New-PSWorkflowExecutionOption
returnerar.
Alternativen för sessioner som använder sessionskonfigurationen bestäms av värdena för sessionsalternativen och sessionskonfigurationsalternativen. Om inget annat anges har de alternativ som angetts i sessionen, till exempel med hjälp av cmdleten New-PSSessionOption
, företräde framför de alternativ som angetts i sessionskonfigurationen. Sessionsalternativvärden kan dock inte överskrida de högsta värden som anges i sessionskonfigurationen.
Den här parametern introducerades i PowerShell 3.0.
Typ: | PSSessionTypeOption |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-ShowSecurityDescriptorUI
Anger att den här cmdleten visar ett egenskapsblad som hjälper dig att skapa SDDL för sessionskonfigurationen. Egenskapsbladet visas när du har angett Register-PSSessionConfiguration
kommandot och startar sedan om WinRM-tjänsten .
När du anger behörigheterna för konfigurationen ska du komma ihåg att användarna måste ha minst behörigheten Kör (Anropa) för att kunna använda sessionskonfigurationen i en session.
Du kan inte använda parametern SecurityDescriptorSDDL och den här parametern i samma kommando.
Typ: | SwitchParameter |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-StartupScript
Anger den fullständigt kvalificerade sökvägen för ett PowerShell-skript. Det angivna skriptet körs i den nya sessionen som använder sessionskonfigurationen.
Du kan använda skriptet för att dessutom konfigurera sessionen. Om skriptet genererar ett fel, inte ens ett icke-avslutande fel, skapas inte sessionen och New-PSSession
kommandot misslyckas.
Typ: | String |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-ThreadApartmentState
Anger lägenhetstillståndet för den trådmodul som ska användas. Godtagbara värden är:
- Okänt
- MTA
- STA
Typ: | ApartmentState |
Godkända värden: | STA, MTA, Unknown |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-ThreadOptions
Anger hur trådar skapas och används när ett kommando körs i sessionen. De acceptabla värdena för den här parametern är:
- Standardvärde
- ReuseThread
- UseCurrentThread
- UseNewThread
Standardvärdet är UseCurrentThread.
Mer information finns i PSThreadOptions Enumeration.
Typ: | PSThreadOptions |
Godkända värden: | Default, UseNewThread, ReuseThread, UseCurrentThread |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-TransportOption
Anger transportalternativet.
Den här parametern introducerades i PowerShell 3.0.
Typ: | PSTransportOption |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-UseSharedProcess
Använd bara en process för att vara värd för alla sessioner som startas av samma användare och använda samma sessionskonfiguration. Som standard körs varje session i sin egen process.
Den här parametern introducerades i PowerShell 3.0.
Typ: | SwitchParameter |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-WhatIf
Visar vad som skulle hända om cmdleten kördes. Cmdleten körs inte.
Typ: | SwitchParameter |
Alias: | wi |
Position: | Named |
Standardvärde: | False |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
Indata
None
Du kan inte skicka objekt till den här cmdleten.
Utdata
Kommentarer
Den här cmdleten är endast tillgänglig på Windows-plattformar.
Om du vill köra den här cmdleten måste du starta PowerShell med alternativet Kör som administratör .
Den här cmdleten genererar XML som representerar en plugin-konfiguration för Web Services for Management (WS-Management) och skickar XML till WS-Management, som registrerar plugin-programmet på den lokala datorn (New-Item wsman:\localhost\plugin
).
Egenskaperna för ett sessionskonfigurationsobjekt varierar med de alternativ som angetts för sessionskonfigurationen och värdena för dessa alternativ. Sessionskonfigurationer som använder en sessionskonfigurationsfil har dessutom ytterligare egenskaper.