Udostępnij za pośrednictwem


Register-PSSessionConfiguration

Tworzy i rejestruje nową konfigurację sesji.

Składnia

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

Opis

To polecenie cmdlet jest dostępne tylko na platformie Windows.

Polecenie Register-PSSessionConfiguration cmdlet tworzy i rejestruje nową konfigurację sesji na komputerze lokalnym. Jest to zaawansowane polecenie cmdlet, którego można użyć do tworzenia sesji niestandardowych dla użytkowników zdalnych.

Każda sesja programu PowerShell (PSSession) używa konfiguracji sesji, znanej również jako punkt końcowy. Gdy użytkownicy tworzą sesję, która łączy się z komputerem, mogą wybrać konfigurację sesji lub użyć domyślnej konfiguracji sesji zarejestrowanej podczas włączania komunikacji zdalnej programu PowerShell. Użytkownicy mogą również ustawić zmienną preferencji $PSSessionConfigurationName, która określa domyślną konfigurację sesji zdalnych utworzonych w bieżącej sesji.

Konfiguracja sesji definiuje środowisko sesji zdalnej. Konfiguracja może określić, które polecenia i elementy językowe są dostępne w sesji, i może zawierać ustawienia, które chronią komputer, takie jak te, które ograniczają ilość danych, które sesja może odbierać zdalnie w jednym obiekcie lub poleceniu. Deskryptor zabezpieczeń konfiguracji sesji określa, którzy użytkownicy mają uprawnienia do korzystania z konfiguracji sesji.

Elementy konfiguracji można zdefiniować przy użyciu zestawu, który implementuje nową klasę konfiguracji i za pomocą skryptu uruchamianego w sesji. Począwszy od programu PowerShell 3.0, można również użyć pliku konfiguracji sesji do zdefiniowania konfiguracji sesji.

Aby uzyskać informacje o konfiguracjach sesji, zobacz about_Session_Configurations. Aby uzyskać informacje o plikach konfiguracji sesji, zobacz about_Session_Configuration_Files.

Przykłady

Przykład 1. Rejestrowanie konfiguracji nowej sesji programuShell

W tym przykładzie rejestrujemy konfigurację sesji programu NewShell . Parametry AssemblyName i ApplicationBase określają lokalizację pliku MyShell.dll , który określa polecenia cmdlet i dostawców w konfiguracji sesji. Parametr ConfigurationTypeName określa klasę konfiguracji do użycia z zestawu.

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

Aby użyć tej konfiguracji, wpisz New-PSSession -ConfigurationName newshell.

Przykład 2. Rejestrowanie konfiguracji sesji programu MaintenanceShell

W tym przykładzie zarejestrowano konfigurację sesji programu MaintenanceShell na komputerze lokalnym. Parametr StartupScript określa Maintenance.ps1 skrypt.

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

Gdy użytkownik używa polecenia i wybiera konfigurację New-PSSessionprogramu MaintenanceShell , Maintenance.ps1 skrypt jest uruchamiany w nowej sesji. Skrypt może skonfigurować sesję. Obejmuje to importowanie modułów i ustawianie zasad wykonywania dla sesji. Jeśli skrypt generuje błędy, w tym błędy niezwiązane z kończeniem, New-PSSession polecenie kończy się niepowodzeniem.

Przykład 3. Rejestrowanie konfiguracji sesji

W tym przykładzie zarejestrowano konfigurację sesji programu AdminShell .

Zmienna $sessionParams jest tabelą skrótową zawierającą wszystkie wartości parametrów. Ta tabela skrótu jest przekazywana do polecenia cmdlet przy użyciu splattingu programu PowerShell. Polecenie Register-PSSessionConfiguration używa parametru SecurityDescritorSDDL w celu określenia sdDL w wartości $sddl zmiennej i parametru MaximumReceivedObjectSizeMB w celu zwiększenia limitu rozmiaru obiektu. Używa również parametru StartupScript do określenia skryptu, który konfiguruje sesję.

$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

Przykład 4. Zwracanie elementu kontenera konfiguracji

W tym przykładzie pokazano, jak zarejestrować konfigurację programu MaintenanceShell . Register-PSSessionConfiguration zwraca obiekt WSManConfigContainerElement przechowywany w zmiennej $s . Format-List wyświetla wszystkie właściwości zwróconego obiektu. Właściwość PSPath pokazuje, że obiekt jest przechowywany w katalogu dysku WSMan: . Get-ChildItem (alias dir) wyświetla elementy w ścieżce WSMan:\LocalHost\PlugIn . Obejmują one nową konfigurację programu MaintenanceShell i dwie domyślne konfiguracje, które są dostarczane z programem 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}

Przykład 5. Rejestrowanie konfiguracji sesji przy użyciu skryptu uruchamiania

W tym przykładzie utworzymy i zarejestrujemy konfigurację sesji WithProfile . Parametr StartupScript kieruje program PowerShell do uruchomienia określonego skryptu dla dowolnej sesji, która używa konfiguracji sesji.

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

Skrypt zawiera jedno polecenie, które używa określania kropki w celu uruchomienia profilu CurrentUserAllHosts użytkownika w bieżącym zakresie sesji.

Aby uzyskać więcej informacji na temat profilów, zobacz about_Profiles. Aby uzyskać więcej informacji na temat określania źródła kropki, zobacz about_Scopes.

Parametry

-AccessMode

Włącza i wyłącza konfigurację sesji i określa, czy może być używany na potrzeby sesji zdalnych lub lokalnych na komputerze. Dopuszczalne wartości dla tego parametru to:

  • Wyłączona. Wyłącza konfigurację sesji. Nie można jej używać do zdalnego lub lokalnego dostępu do komputera.
  • Lokalnych. Umożliwia użytkownikom komputera lokalnego korzystanie z konfiguracji sesji w celu utworzenia lokalnej sesji sprzężenia zwrotnego na tym samym komputerze, ale odmawia dostępu do użytkowników zdalnych.
  • Zdalnego. Umożliwia lokalnym i zdalnym użytkownikom używanie konfiguracji sesji do tworzenia sesji i uruchamiania poleceń na tym komputerze.

Wartość domyślna to Zdalne.

Inne polecenia cmdlet mogą później zastąpić wartość tego parametru. Na przykład Enable-PSRemoting polecenie cmdlet umożliwia dostęp zdalny do wszystkich konfiguracji sesji, Enable-PSSessionConfiguration polecenie cmdlet włącza konfiguracje sesji, a Disable-PSRemoting polecenie cmdlet uniemożliwia zdalny dostęp do wszystkich konfiguracji sesji.

Ten parametr został wprowadzony w programie 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

Określa ścieżkę pliku zestawu (*.dll), który jest określony w wartości parametru AssemblyName . Użyj tego parametru, gdy wartość parametru AssemblyName nie zawiera ścieżki. Ustawieniem domyślnym jest bieżący katalog.

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

-AssemblyName

Określa nazwę pliku zestawu (*.dll), w którym zdefiniowano typ konfiguracji. Ścieżkę .dll można określić w tym parametrze lub w wartości parametru ApplicationBase .

Ten parametr jest wymagany podczas określania parametru ConfigurationTypeName .

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

-ConfigurationTypeName

Określa w pełni kwalifikowaną nazwę typu microsoft .NET Framework, który jest używany do tej konfiguracji. Określony typ musi implementować klasę System.Management.Automation.Remoting.PSSessionConfiguration .

Aby określić plik zestawu (*.dll), który implementuje typ konfiguracji, określ parametry AssemblyName i ApplicationBase .

Tworzenie typu umożliwia kontrolowanie większej liczby aspektów konfiguracji sesji, takich jak uwidacznianie lub ukrywanie niektórych parametrów poleceń cmdlet lub ustawianie limitów rozmiaru danych i rozmiaru obiektu, których użytkownicy nie mogą zastąpić.

Jeśli pominiesz ten parametr, dla konfiguracji sesji zostanie użyta klasa DefaultRemotePowerShellConfiguration .

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

-Confirm

Monituje o potwierdzenie przed uruchomieniem polecenia cmdlet.

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

-Force

Pomija wszystkie monity użytkownika i uruchamia ponownie usługę WinRM bez monitowania. Ponowne uruchomienie usługi powoduje, że zmiana konfiguracji będzie skuteczna.

Aby zapobiec ponownemu uruchomieniu i pominąć monit o ponowne uruchomienie, określ parametr NoServiceRestart .

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

-MaximumReceivedDataSizePerCommandMB

Określa limit ilości danych, które można wysłać do tego komputera w dowolnym pojedynczym poleceniu zdalnym. Wprowadź rozmiar danych w megabajtach (MB). Wartość domyślna to 50 MB.

Jeśli limit rozmiaru danych jest zdefiniowany w typie konfiguracji określonym w parametrze ConfigurationTypeName , używany jest limit w typie konfiguracji i wartość tego parametru jest ignorowana.

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

-MaximumReceivedObjectSizeMB

Określa limit ilości danych, które można wysłać do tego komputera w dowolnym obiekcie. Wprowadź rozmiar danych w megabajtach. Wartość domyślna to 10 MB.

Jeśli limit rozmiaru obiektu jest zdefiniowany w typie konfiguracji określonym w parametrze ConfigurationTypeName , używany jest limit w typie konfiguracji i wartość tego parametru jest ignorowana.

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

-ModulesToImport

Określa moduły, które są automatycznie importowane do sesji korzystających z konfiguracji sesji.

Domyślnie tylko program Microsoft.PowerShell.Core jest importowany do sesji. Jeśli polecenia cmdlet nie zostaną wykluczone, możesz użyć Import-Module polecenia w celu dodania modułów do sesji.

Moduły określone w tej wartości parametru są importowane oprócz modułów, które są określone przez parametr SessionType i wymienione w kluczu ModulesToImport w pliku konfiguracji sesji (New-PSSessionConfigurationFile). Jednak ustawienia w pliku konfiguracji sesji mogą ukrywać polecenia eksportowane przez moduły lub uniemożliwiać użytkownikom korzystanie z nich.

Ten parametr został wprowadzony w programie PowerShell 3.0.

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

-Name

Określa nazwę konfiguracji sesji. Ten parametr jest wymagany.

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

-NoServiceRestart

Nie uruchamia ponownie usługi WinRM i pomija monit o ponowne uruchomienie usługi.

Domyślnie po uruchomieniu Register-PSSessionConfiguration polecenia zostanie wyświetlony monit o ponowne uruchomienie usługi WinRM w celu wprowadzenia nowej konfiguracji sesji. Dopóki usługa WinRM nie zostanie ponownie uruchomiona, nowa konfiguracja sesji nie będzie skuteczna.

Aby ponownie uruchomić usługę WinRM bez monitowania, określ parametr Force . Aby ręcznie uruchomić ponownie usługę WinRM , użyj Restart-Service polecenia cmdlet .

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

-Path

Określa ścieżkę i nazwę pliku konfiguracji sesji (pssc), taki jak plik utworzony przez New-PSSessionConfigurationFile. Jeśli pominięto ścieżkę, wartością domyślną jest bieżący katalog.

Ten parametr został wprowadzony w programie PowerShell 3.0.

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

-ProcessorArchitecture

Określa, czy jest uruchamiana 32-bitowa, czy 64-bitowa wersja procesu programu PowerShell w sesjach korzystających z tej konfiguracji sesji. Dopuszczalne wartości tego parametru to: x86 (32-bitowe) i AMD64 (64-bitowe). Wartość domyślna jest określana przez architekturę procesora komputera, który hostuje konfigurację sesji.

Tego parametru można użyć do utworzenia sesji 32-bitowej na komputerze 64-bitowym. Próba utworzenia 64-bitowego procesu na komputerze 32-bitowym kończy się niepowodzeniem.

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

-PSVersion

Określa wersję programu PowerShell w sesjach korzystających z tej konfiguracji sesji.

Wartość tego parametru ma pierwszeństwo przed wartością klucza PowerShellVersion w pliku konfiguracji sesji.

Ten parametr został wprowadzony w programie PowerShell 3.0.

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

-RunAsCredential

Określa poświadczenia dla poleceń w sesji. Domyślnie polecenia są uruchamiane z uprawnieniami bieżącego użytkownika.

Ten parametr został wprowadzony w programie PowerShell 3.0.

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

-SecurityDescriptorSddl

Określa ciąg języka SDDL (Security Descriptor Definition Language) dla konfiguracji.

Ten ciąg określa uprawnienia wymagane do korzystania z nowej konfiguracji sesji. Aby użyć konfiguracji sesji w sesji, użytkownicy muszą mieć co najmniej uprawnienie Wykonaj (Wywołaj) dla konfiguracji.

Jeśli deskryptor zabezpieczeń jest złożony, rozważ użycie parametru ShowSecurityDescriptorUI zamiast tego parametru. Nie można użyć obu parametrów w tym samym poleceniu.

W przypadku pominięcia tego parametru główny plik SDDL dla usługi WinRM jest używany na potrzeby tej konfiguracji. Aby wyświetlić lub zmienić główny plik SDDL, użyj dostawcy WSMan. Na przykład: Get-Item wsman:\localhost\service\rootSDDL. Aby uzyskać więcej informacji na temat dostawcy WSMan, wpisz Get-Help wsman.

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

-SessionTypeOption

Określa opcje specyficzne dla typu dla konfiguracji sesji. Wprowadź obiekt opcji typu sesji, taki jak obiekt PSWorkflowExecutionOption zwracany przez New-PSWorkflowExecutionOption polecenie cmdlet.

Opcje sesji korzystających z konfiguracji sesji są określane przez wartości opcji sesji i opcji konfiguracji sesji. O ile nie określono, opcje ustawione w sesji, takie jak przy użyciu New-PSSessionOption polecenia cmdlet, mają pierwszeństwo przed opcjami ustawionymi w konfiguracji sesji. Jednak wartości opcji sesji nie mogą przekraczać maksymalnych wartości ustawionych w konfiguracji sesji.

Ten parametr został wprowadzony w programie PowerShell 3.0.

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

-ShowSecurityDescriptorUI

Wskazuje, że to polecenie cmdlet wyświetla arkusz właściwości, który pomaga utworzyć sdDL dla konfiguracji sesji. Po wprowadzeniu Register-PSSessionConfiguration polecenia zostanie wyświetlony arkusz właściwości, a następnie uruchom ponownie usługę WinRM .

Podczas ustawiania uprawnień do konfiguracji należy pamiętać, że użytkownicy muszą mieć co najmniej uprawnienie Wykonaj (Wywołaj), aby używać konfiguracji sesji w sesji.

Nie można użyć parametru SecurityDescriptorSDDL i tego parametru w tym samym poleceniu.

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

-StartupScript

Określa w pełni kwalifikowaną ścieżkę skryptu programu PowerShell. Określony skrypt jest uruchamiany w nowej sesji, która używa konfiguracji sesji.

Możesz użyć skryptu, aby dodatkowo skonfigurować sesję. Jeśli skrypt generuje błąd, nawet błąd niepowodujący zakończenia, sesja nie zostanie utworzona i New-PSSession polecenie zakończy się niepowodzeniem.

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

-ThreadApartmentState

Określa stan mieszkania modułu wątkowego do użycia. Dopuszczalne wartości to:

  • Nieznane
  • MTA
  • STA
Type:ApartmentState
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ThreadOptions

Określa, jak wątki są tworzone i używane, gdy polecenie jest uruchamiane w sesji. Dopuszczalne wartości dla tego parametru to:

  • Default
  • Ponowne użycieWczystego
  • UseCurrentThread
  • UseNewThread

Wartość domyślna to UseCurrentThread.

Aby uzyskać więcej informacji, zobacz PSThreadOptions Enumeration (Wyliczenie PSThreadOptions).

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

-TransportOption

Określa opcję transportu.

Ten parametr został wprowadzony w programie PowerShell 3.0.

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

-UseSharedProcess

Użyj tylko jednego procesu, aby hostować wszystkie sesje uruchomione przez tego samego użytkownika i używać tej samej konfiguracji sesji. Domyślnie każda sesja jest hostowana we własnym procesie.

Ten parametr został wprowadzony w programie PowerShell 3.0.

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

-WhatIf

Pokazuje, co się stanie po uruchomieniu polecenia cmdlet. Polecenie cmdlet nie zostało uruchomione.

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

Dane wejściowe

None

Nie można przekazać potoku danych wejściowych do tego polecenia cmdlet.

Dane wyjściowe

WSManConfigContainerElement

Uwagi

To polecenie cmdlet jest dostępne tylko na platformach systemu Windows.

Aby uruchomić to polecenie cmdlet, należy uruchomić program PowerShell przy użyciu opcji Uruchom jako administrator .

To polecenie cmdlet generuje kod XML, który reprezentuje konfigurację wtyczki usług sieci Web do zarządzania (WS-Management) i wysyła kod XML do usługi WS-Management, która rejestruje wtyczkę na komputerze lokalnym (New-Item wsman:\localhost\plugin).

Właściwości obiektu konfiguracji sesji różnią się w zależności od opcji ustawionych dla konfiguracji sesji i wartości tych opcji. Ponadto konfiguracje sesji korzystające z pliku konfiguracji sesji mają dodatkowe właściwości.