Register-PSSessionConfiguration

Modul:

Microsoft.PowerShell.Core

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 ä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 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.
• 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. 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.

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 parametern ApplicationBase .

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ä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 .

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 den konfigurationstyp 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 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.

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 göra den nya sessionskonfigurationen effektiv. 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. 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.

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

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

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 dessutom konfigurera sessionen. 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 den trådmodul 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 objekt till den här cmdleten.

Utdata

WSManConfigContainerElement

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.

Relaterade länkar

• Disable-PSSessionConfiguration
• Enable-PSSessionConfiguration
• Get-PSSessionConfiguration
• New-PSSessionConfigurationFile
• Set-PSSessionConfiguration
• Test-PSSessionConfigurationFile
• Unregister-PSSessionConfiguration
• WSMan-provider
• about_Session_Configurations
• about_Session_Configuration_Files