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 sessionen som är registrerad 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 den 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äkerhetsbeskrivning 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 NewShell-sessionskonfiguration
I det här exemplet registrerar vi konfigurationen för NewShell-sessionen . Parametrarna AssemblyName och ApplicationBase anger platsen förMyShell.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
Det här exemplet registrerar 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 inkluderar 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
Det här exemplet registrerar AdminShell-sessionskonfigurationen .
Variabeln $sessionParams
är en hashtabell som innehåller alla parametervärden. Den här hashtabellen skickas till cmdleten med hjälp av PowerShell-plattning. 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;FA;SA;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. Egenskapen PSPath visar att objektet lagras i en katalog för 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 dirigerar PowerShell till 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.
- Lokala. 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.
- Fjärr. 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. Cmdleten Enable-PSRemoting
tillåter till exempel 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.
Type: | PSSessionConfigurationAccessMode |
Accepted values: | Disabled, Local, Remote |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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 ApplicationBase-parametern .
Den här parametern krävs när du anger parametern ConfigurationTypeName .
Type: | String |
Position: | 1 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | 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.
Type: | String |
Position: | 2 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Confirm
Uppmanar dig att bekräfta innan du kör cmdleten.
Type: | SwitchParameter |
Aliases: | cf |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Force
Undertrycker alla användarfrågor och startar om WinRM-tjänsten utan att fråga. Om du startar om tjänsten börjar konfigurationsändringen gälla.
Om du vill förhindra en omstart och ignorera omstartsprompten anger du parametern NoServiceRestart .
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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 konfigurationstypen som anges i parametern ConfigurationTypeName används gränsen i konfigurationstypen och värdet för den här parametern ignoreras.
Type: | Nullable<T>[Double] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumReceivedObjectSizeMB
Anger en gräns för mängden 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 konfigurationstypen som anges i parametern ConfigurationTypeName används gränsen i konfigurationstypen och värdet för den här parametern ignoreras.
Type: | Nullable<T>[Double] |
Position: | Named |
Default value: | 10 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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.
Type: | Object[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Name
Anger ett namn för sessionskonfigurationen. Den här parametern krävs.
Type: | String |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-NoServiceRestart
Startar inte om WinRM-tjänsten och undertrycker uppmaningen att starta om tjänsten.
När du kör ett Register-PSSessionConfiguration
kommando uppmanas du som standard att starta om WinRM-tjänsten för att den nya sessionskonfigurationen ska börja gälla. Den nya sessionskonfigurationen gäller inte förrän WinRM-tjänsten har startats om.
Om du vill starta om WinRM-tjänsten utan att fråga anger du force-parametern. Om du vill starta om WinRM-tjänsten manuellt använder du cmdleten Restart-Service
.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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.
Type: | String |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | 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. Acceptabla värden 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.
Type: | String |
Aliases: | PA |
Accepted values: | x86, amd64 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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.
Type: | Version |
Aliases: | PowerShellVersion |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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.
Type: | PSCredential |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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 minst ha 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
.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SessionTypeOption
Anger typspecifika alternativ för sessionskonfigurationen. Ange ett alternativobjekt för sessionstyp, till exempel objektet PSWorkflowExecutionOption 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 anges i sessionskonfigurationen. Värdena för sessionsalternativ får dock inte överskrida de högsta värden som angetts i sessionskonfigurationen.
Den här parametern introducerades i PowerShell 3.0.
Type: | PSSessionTypeOption |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ShowSecurityDescriptorUI
Anger att denna cmdlet 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 måste du komma ihåg att användarna måste ha minst kör-behörighet (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.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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 konfigurera sessionen ytterligare. Om skriptet genererar ett fel, även ett icke-avslutande fel, skapas inte sessionen och New-PSSession
kommandot misslyckas.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ThreadApartmentState
Anger lägenhetstillståndet för trådmodulen som ska användas. Godtagbara värden är:
- Okänt
- MTA
- STA
Type: | ApartmentState |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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.
Type: | PSThreadOptions |
Accepted values: | Default, UseNewThread, ReuseThread, UseCurrentThread |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-TransportOption
Anger transportalternativet.
Den här parametern introducerades i PowerShell 3.0.
Type: | PSTransportOption |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-WhatIf
Visar vad som skulle hända om cmdleten kördes. Cmdleten körs inte.
Type: | SwitchParameter |
Aliases: | wi |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Indata
None
Du kan inte skicka indata 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 WS-Management-plugin-konfiguration (Web Services for 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. Dessutom har sessionskonfigurationer som använder en sessionskonfigurationsfil ytterligare egenskaper.