Set-PSSessionConfiguration

Zmienia właściwości konfiguracji zarejestrowanej sesji.

Składnia

Set-PSSessionConfiguration
   [-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>]
Set-PSSessionConfiguration
   [-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>]
Set-PSSessionConfiguration
   [-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 Set-PSSessionConfiguration cmdlet zmienia właściwości konfiguracji sesji na komputerze lokalnym.

Użyj parametru Name , aby zidentyfikować konfigurację sesji, którą chcesz zmienić. Użyj innych parametrów, aby określić nowe wartości właściwości konfiguracji sesji. Aby usunąć wartość właściwości z konfiguracji i użyć wartości domyślnej, wprowadź pusty ciąg ("") lub wartość $Null dla odpowiedniego parametru.

Począwszy od programu PowerShell 3.0, można użyć pliku konfiguracji sesji do zdefiniowania konfiguracji sesji. Ta funkcja zapewnia prostą i wykrywalną metodę ustawiania i zmieniania właściwości sesji korzystających z konfiguracji sesji. Aby określić plik konfiguracji sesji, użyj parametru Ścieżka .Set-PSSessionConfiguration Aby uzyskać informacje o plikach konfiguracji sesji, zobacz about_Session_Configuration_Files. Aby uzyskać informacje o sposobie tworzenia i modyfikowania pliku konfiguracji sesji, zobacz New-PSSessionConfigurationFile polecenie cmdlet .

Konfiguracje sesji definiują środowisko sesji zdalnych (PSSessions), które łączą się z komputerem lokalnym. Każda sesja PSSession używa konfiguracji sesji. Konfiguracja sesji określa funkcje sesji psSession, takie jak moduły dostępne w sesji, polecenia cmdlet, które mogą być uruchamiane, tryb języka, przydziały i limity czasu. Deskryptor zabezpieczeń konfiguracji sesji określa, kto może używać konfiguracji sesji do nawiązywania połączenia z komputerem lokalnym. Aby uzyskać więcej informacji na temat konfiguracji sesji, zobacz Informacje o konfiguracjach sesji.

Aby wyświetlić właściwości konfiguracji sesji, użyj Get-PSSessionConfiguration polecenia cmdlet lub dostawcy WSMan. Aby uzyskać więcej informacji na temat dostawcy WSMan, wpisz Get-Help WSMan.

Przykłady

Przykład 1: Tworzenie i zmienianie konfiguracji sesji

W tym przykładzie pokazano, jak dodać i usunąć skrypt uruchamiania z konfiguracji.

Pierwsze polecenie tworzy konfigurację programu AdminShell . Drugie polecenie dodaje AdminConfig.ps1 skrypt do konfiguracji. Zmiana jest obowiązująca po ponownym uruchomieniu usługi WinRM. Trzecie polecenie usuwa AdminConfig.ps1 skrypt z konfiguracji.

Register-PSSessionConfiguration -Name "AdminShell" -AssemblyName "C:\Shells\AdminShell.dll" -ConfigurationTypeName "AdminClass"
Set-PSSessionConfiguration -Name "AdminShell" -StartupScript "AdminConfig.ps1"
Set-PSSessionConfiguration -Name "AdminShell" -StartupScript $Null

Przykład 2. Wyświetlanie wyników

Ten przykład zwiększa wartość właściwości MaximumReceivedObjectSizeMB na 20. To polecenie wyświetla również monit o ponowne uruchomienie usługi WinRM . Zmiana nie jest obowiązująca, dopóki usługa WinRM nie zostanie ponownie uruchomiona.

Set-PSSessionConfiguration -Name "IncObj" -MaximumReceivedObjectSizeMB 20

WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\IncObj\InitializationParameters

ParamName                       ParamValue
---------                       ----------
psmaximumreceivedobjectsizemb   20

"Restart WinRM service"
WinRM service need to be restarted to make the changes effective. Do you want to run the command "restart-service winrm"?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y

Przykład 3. Wyświetlanie wyników na różne sposoby

W tym przykładzie Set-PSSessionConfiguration zmienia skrypt uruchamiania w konfiguracji sesji programu MaintenanceShell na Maintenance.ps1. Dane wyjściowe pokazują zmianę i monituje o ponowne uruchomienie usługi WinRM . Odpowiedź to y (tak).

Get-PSSessionConfiguration pobiera konfigurację sesji programu MaintenanceShell . Operator potoku (|) wysyła wyniki polecenia do Format-List, który wyświetla wszystkie właściwości obiektu konfiguracji na liście. Następnie przy użyciu dostawcy WSMan wyświetlimy parametry inicjowania konfiguracji programu MaintenanceShell . Get-ChildItem Pobiera elementy podrzędne w węźle InitializationParameters dla wtyczki MaintenanceShell . Aby uzyskać więcej informacji na temat dostawcy WSMan, wpisz Get-Help wsman.

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

WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell\InitializationParameters

ParamName            ParamValue
---------            ----------
startupscript        c:\ps-test\Mainte...

"Restart WinRM service"
WinRM service need to be restarted to make the changes effective. Do you want to run
the command "restart-service winrm"?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y

Get-PSSessionConfiguration MaintenanceShell | Format-List -Property *

xmlns            : http://schemas.microsoft.com/wbem/wsman/1/config/PluginConfiguration
Name             : MaintenanceShell
Filename         : %windir%\system32\pwrshplugin.dll
SDKVersion       : 1
XmlRenderingType : text
lang             : en-US
PSVersion        : 2.0
startupscript    : c:\ps-test\Maintenance.ps1
ResourceUri      : http://schemas.microsoft.com/powershell/MaintenanceShell
SupportsOptions  : true
ExactMatch       : true
Capability       : {Shell}
Permission       :

Get-ChildItem WSMan:\localhost\Plugin\MaintenanceShell\InitializationParameters

ParamName     ParamValue
---------     ----------
PSVersion     2.0
startupscript c:\ps-test\Maintenance.ps1

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:

  • Disabled. Wyłącza konfigurację sesji. Nie można go używać do zdalnego lub lokalnego dostępu do komputera. Ta wartość ustawia właściwość Enabled konfiguracji sesji (WSMan:\<ComputerName>\PlugIn\<SessionConfigurationName>\Enabled) na False.
  • Local. Dodaje wpis Network_Deny_All do deskryptora zabezpieczeń konfiguracji sesji. Użytkownicy komputera lokalnego mogą używać konfiguracji sesji do tworzenia lokalnej sesji sprzężenia zwrotnego na tym samym komputerze, ale użytkownicy zdalni nie mają dostępu.
  • Remote. Usuwa Deny_All i Network_Deny_All wpisy z deskryptorów zabezpieczeń konfiguracji sesji. Użytkownicy komputerów lokalnych i zdalnych mogą używać konfiguracji sesji do tworzenia sesji i uruchamiania poleceń na tym komputerze.

Wartość domyślna to Remote.

Inne polecenia cmdlet mogą później zastąpić wartość tego parametru. Na przykład Enable-PSRemoting polecenie cmdlet włącza wszystkie konfiguracje sesji na komputerze i zezwala na dostęp zdalny do nich, a Disable-PSRemoting polecenie cmdlet zezwala tylko na dostęp lokalny do wszystkich konfiguracji sesji na komputerze.

Ten parametr został wprowadzony w programie PowerShell 3.0.

Type:PSSessionConfigurationAccessMode
Accepted values:Disabled, Local, Remote
Position:Named
Default value:None
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 .

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

-AssemblyName

Określa nazwę zestawu. To polecenie cmdlet tworzy konfigurację sesji na podstawie klasy zdefiniowanej w zestawie.

Wprowadź nazwę pliku zestawu lub pełną ścieżkę pliku zestawu .dll , który definiuje konfigurację sesji. Jeśli wprowadzisz tylko nazwę pliku, możesz wprowadzić ścieżkę w wartości parametru ApplicationBase .

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

-ConfigurationTypeName

Określa typ konfiguracji sesji zdefiniowanej w zestawie w parametrze AssemblyName . Określony typ musi implementować klasę System.Management.Automation.Remoting.PSSessionConfiguration .

Ten parametr jest wymagany podczas określania nazwy zestawu.

Type:String
Position:2
Default value:None
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
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 sprawia, że zmiana konfiguracji jest efektywna.

Aby zapobiec ponownemu uruchomieniu i pominąć monit o ponowne uruchomienie, użyj parametru NoServiceRestart .

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

-MaximumReceivedDataSizePerCommandMB

Określa limit ilości danych, które mogą być wysyłane do tego komputera w dowolnym pojedynczym poleceniu zdalnym. Wprowadź rozmiar danych w megabajtach (MB). Wartość domyślna to 50.

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

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

-MaximumReceivedObjectSizeMB

Określa limity ilości danych, które mogą być wysyłane do tego komputera w dowolnym pojedynczym obiekcie. Wprowadź rozmiar danych w megabajtach. Wartość domyślna to 10.

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

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

-ModulesToImport

Określa moduły i przystawki, które są automatycznie importowane do sesji korzystających z konfiguracji sesji. Wprowadź moduł i nazwy przystawek.

Domyślnie tylko moduł Microsoft.PowerShell.Core jest importowany do sesji, ale jeśli polecenia cmdlet nie zostaną wykluczone, można użyć Import-Module poleceń cmdlet i Add-PSSnapin , aby dodać moduły i przystawki do sesji.

Moduły określone w tej wartości parametru są importowane oprócz modułów określonych 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.

Moduły określone w tej wartości parametru zastępują listę modułów określonych parametrem Register-PSSessionConfigurationModulesToImport polecenia cmdlet.

Ten parametr został wprowadzony w programie PowerShell 3.0.

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

-Name

Określa nazwę konfiguracji sesji, którą chcesz zmienić.

Nie można użyć tego parametru, aby zmienić nazwę konfiguracji sesji.

Type:String
Position:0
Default value:None
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 polecenia Set-PSSessionConfigurationzostanie 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, użyj parametru Force . Aby ręcznie uruchomić ponownie usługę WinRM , użyj Restart-Service polecenia cmdlet .

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

-Path

Określa ścieżkę pliku konfiguracji sesji (.pssc), na przykład ścieżkę utworzoną New-PSSessionConfigurationFile przez polecenie cmdlet. Jeśli pominięto ścieżkę, wartością domyślną jest bieżący katalog.

Aby uzyskać informacje na temat modyfikowania pliku konfiguracji sesji, zobacz temat pomocy dla New-PSSessionConfigurationFile polecenia cmdlet.

Ten parametr został wprowadzony w programie PowerShell 3.0.

Type:String
Position:Named
Default value:None
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
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
Accept pipeline input:False
Accept wildcard characters:False

-SecurityDescriptorSddl

Określa inny 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 Execute(Invoke) uprawnienia do konfiguracji.

Aby użyć domyślnego deskryptora zabezpieczeń dla konfiguracji, wprowadź pusty ciąg ("") lub wartość $Null. Wartość domyślna to główny plik SDDL na WSMan: dysku.

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

Type:String
Position:Named
Default value:None
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 w New-PSSessionOption przypadku 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
Accept pipeline input:False
Accept wildcard characters:False

-ShowSecurityDescriptorUI

Gdy ten parametr jest używany, polecenie cmdlet otwiera arkusz właściwości, który ułatwia utworzenie nowego zestawu SDDL dla konfiguracji sesji. Arkusz właściwości zostanie wyświetlony po uruchomieniu Set-PSSessionConfiguration polecenia, a następnie ponownie uruchom usługę WinRM .

Po ustawieniu uprawnień do konfiguracji należy pamiętać, że użytkownicy muszą mieć co najmniej Execute(Invoke) uprawnienia do korzystania z 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
Accept pipeline input:False
Accept wildcard characters:False

-StartupScript

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

Aby usunąć skrypt uruchamiania z konfiguracji sesji, wprowadź pusty ciąg ("") lub wartość $Null.

Możesz użyć skryptu uruchamiania, aby dodatkowo skonfigurować sesję użytkownika. 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
Accept pipeline input:False
Accept wildcard characters:False

-ThreadApartmentState

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

  • Unknown
  • MTA
  • STA
Type:ApartmentState
Accepted values:STA, MTA, Unknown
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-ThreadOptions

Określa ustawienie opcji wątku w konfiguracji. To ustawienie określa sposób tworzenia wątków i ich użycia podczas wykonywania polecenia w sesji. Dopuszczalne wartości dla tego parametru to:

  • Default
  • ReuseThread
  • 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
Accept pipeline input:False
Accept wildcard characters:False

-TransportOption

Określa opcje transportu dla konfiguracji sesji. Wprowadź obiekt opcji transportu, taki jak obiekt WSManConfigurationOption zwracany przez New-PSTransportOption 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 w New-PSSessionOption przypadku 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:PSTransportOption
Position:Named
Default value:None
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
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
Accept pipeline input:False
Accept wildcard characters:False

Dane wejściowe

None

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

Dane wyjściowe

Microsoft.WSMan.Management.WSManConfigLeafElement

Uwagi

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

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

Polecenie Set-PSSessionConfiguration cmdlet nie zmienia nazwy konfiguracji, a dostawca WSMan nie obsługuje Rename-Item polecenia cmdlet. Aby zmienić nazwę konfiguracji sesji, użyj Unregister-PSSessionConfiguration polecenia cmdlet , aby usunąć konfigurację, a następnie użyć Register-PSSessionConfiguration polecenia cmdlet do utworzenia i zarejestrowania nowej konfiguracji sesji.

Możesz użyć Set-PSSessionConfiguration polecenia cmdlet , aby zmienić konfiguracje domyślne Microsoft.PowerShell i Microsoft.PowerShell32 sesji. Nie są chronione. Aby przywrócić oryginalną wersję domyślnej konfiguracji sesji, użyj Unregister-PSSessionConfiguration polecenia cmdlet , aby usunąć konfigurację sesji domyślnej, a następnie użyć Enable-PSRemoting polecenia cmdlet , aby przywrócić ją.

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.

Możesz użyć poleceń na WSMan: dysku, aby zmienić właściwości konfiguracji sesji. Nie można jednak użyć WSMan: dysku w programie PowerShell 2.0, aby zmienić właściwości konfiguracji sesji wprowadzone w programie PowerShell 3.0, takie jak OutputBufferingMode. Windows PowerShell polecenia 2.0 nie generują błędu, ale są nieskuteczne. Aby zmienić właściwości wprowadzone w programie PowerShell 3.0, użyj WSMan: dysku w programie PowerShell 3.0 lub nowszym.