Set-PSSessionConfiguration

Модуль:

Microsoft.PowerShell.Core

Изменяет свойства конфигурации зарегистрированного сеанса.

Синтаксис

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

Описание

Этот командлет доступен только на платформе Windows.

Командлет Set-PSSessionConfiguration изменяет свойства конфигураций сеанса на локальном компьютере.

Используйте Name параметр, чтобы указать конфигурацию сеанса, которую требуется изменить. С помощью других параметров укажите новые значения свойств конфигурации сеанса. Чтобы удалить значение свойства из конфигурации и использовать значение по умолчанию, введите пустую строку ("") или значение для соответствующего $Null параметра.

Начиная с PowerShell 3.0, для определения конфигурации сеанса можно использовать файл конфигурации сеанса. Это простой метод для настройки и изменения свойств сеансов, которые используют одну конфигурацию. Чтобы указать файл конфигурации сеанса, используйте параметр Path для Set-PSSessionConfiguration. Сведения о файлах конфигурации сеанса см. в разделе about_Session_Configuration_Files. Сведения о создании и изменении файла конфигурации сеанса см. в New-PSSessionConfigurationFile разделе Командлет .

Конфигурации сеансов определяют среду удаленных сеансов (PSSessions), которые подключаются к локальному компьютеру. Каждый сеанс PSSession использует конфигурацию сеанса. Конфигурация сеанса определяет функции PSSession, такие как доступные в сеансе модули, командлеты, которые разрешены для выполнения, языковой режим, квоты и время ожидания. Дескриптор безопасности конфигурации сеанса определяет, кто может использовать конфигурацию сеанса для подключения к локальному компьютеру. Дополнительные сведения о конфигурациях сеансов см. в разделе about_Session_Configurations.

Чтобы просмотреть свойства конфигурации сеанса, используйте Get-PSSessionConfiguration командлет или поставщик WSMan. Для получения дополнительных сведений о поставщике WSMan введите Get-Help WSMan.

Примеры

Пример 1. Create и изменение конфигурации сеанса

В этом примере показано, как добавить и удалить скрипт запуска из конфигурации.

Первая команда создает конфигурацию AdminShell . Вторая команда добавляет скрипт в AdminConfig.ps1 конфигурацию. Изменение вступает в силу при перезапуске WinRM. Третья команда удаляет AdminConfig.ps1 скрипт из конфигурации.

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

Пример 2. Отображение результатов

В этом примере значение свойства MaximumReceivedObjectSizeMB увеличивается до 20. Эта команда также предлагает перезапустить службу WinRM . Изменение не вступает в силу до перезапуска службы WinRM .

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

Пример 3. Отображение результатов различными способами

В этом примере Set-PSSessionConfiguration скрипт запуска в конфигурации сеанса MaintenanceShell изменяется на Maintenance.ps1. В выходных данных показано изменение и предлагается перезапустить службу WinRM . Ответ — y (да).

Get-PSSessionConfiguration возвращает конфигурацию сеанса MaintenanceShell . Оператор конвейера (|) отправляет результаты команды Format-Listв , который отображает все свойства объекта конфигурации в списке. Затем, используя поставщик WSMan, мы просматриваем параметры инициализации для конфигурации MaintenanceShell . Get-ChildItem получает дочерние элементы в узле InitializationParameters для подключаемого модуля MaintenanceShell . Для получения дополнительных сведений о поставщике WSMan введите 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

Параметры

-AccessMode

Включает и отключает конфигурацию сеанса и определяет возможность ее использования для удаленных или локальных сеансов компьютера. Допустимые значения для этого параметра:

• Disabled. отключает конфигурацию сеанса. Использовать конфигурацию для локального или удаленного доступа к компьютеру. Это значение задает свойству Enabled конфигурации сеанса (WSMan:\<ComputerName>\PlugIn\<SessionConfigurationName>\Enabled) значение False.
• Local. Добавляет запись Network_Deny_All в дескриптор безопасности конфигурации сеанса. Пользователи локального компьютера могут использовать конфигурацию сеанса для создания локального сеанса замыкания на себя на том же компьютере, но удаленным пользователям отказано в доступе.
• Remote. Удаляет записи Deny_All и Network_Deny_All из дескрипторов безопасности конфигурации сеанса. Пользователи локальных и удаленных компьютеров могут применять конфигурацию сеанса для создания сеансов и выполнения команд на этом компьютере.

Значение по умолчанию — Remote.

Другие командлеты могут переопределить значение этого параметра позже. Например, Enable-PSRemoting командлет включает все конфигурации сеансов на компьютере и разрешает к ним удаленный доступ, а Disable-PSRemoting командлет разрешает только локальный доступ ко всем конфигурациям сеанса на компьютере.

Этот параметр появился в 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

Указывает путь к файлу сборки (*.dll), указанному в значении параметра AssemblyName .

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

-AssemblyName

Задает имя сборки. Этот командлет создает конфигурацию сеанса на основе класса, определенного в сборке.

Введите имя файла или полный путь к файлу сборки .dll , который определяет конфигурацию сеанса. Если ввести только имя файла, можно ввести путь в значении параметра ApplicationBase .

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

-ConfigurationTypeName

Указывает тип конфигурации сеанса, который определен в сборке в параметре AssemblyName. Задаваемый тип должен реализовывать класс System.Management.Automation.Remoting.PSSessionConfiguration.

Этот параметр является обязательным, если указано имя сборки.

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

-Confirm

Запрос подтверждения перед выполнением командлета.

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

-Force

Подавляет все запросы пользователей и перезапускает службу WinRM без запроса. Перезапуск службы обеспечивает вступление изменений конфигурации в силу.

Чтобы предотвратить перезапуск и подавить запрос на перезапуск, используйте параметр NoServiceRestart.

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

-MaximumReceivedDataSizePerCommandMB

Указывает ограничение на объем данных, которые могут быть отправлены на этот компьютер с помощью любой одной удаленной команды. Введите размер данных в мегабайтах (МБ). Значение по умолчанию — 50.

Если ограничение на размер данных определено в типе конфигурации, указанном в параметре ConfigurationTypeName , используется ограничение в типе конфигурации. Значение этого параметра игнорируется.

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

-MaximumReceivedObjectSizeMB

Указывает ограничения на объем данных, которые могут быть отправлены на этот компьютер в любом отдельном объекте. Введите размер данных в мегабайтах. Значение по умолчанию — 10.

Если ограничение на размер объекта определено в типе конфигурации, указанном в параметре ConfigurationTypeName , используется ограничение в типе конфигурации. Значение этого параметра игнорируется.

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

-ModulesToImport

Указывает модули и оснастки, которые автоматически импортируются в сеансы, использующие конфигурацию сеанса. Введите имена модулей и оснасток.

По умолчанию в сеансы импортируется только модуль Microsoft.PowerShell.Core , но если командлеты не исключены, можно использовать Import-Module командлеты и Add-PSSnapin для добавления модулей и оснастки в сеанс.

Модули, указанные в этом значении параметра, импортируются в дополнение к модулям, указанным в файле конфигурации сеанса (New-PSSessionConfigurationFile). При этом параметры в файле конфигурации сеанса могут скрывать экспортируемые модулями команды или запрещать их использование.

Модули, указанные в этом значении параметра, заменяют список модулей, указанных параметром ModulesToImport командлета Register-PSSessionConfiguration .

Этот параметр появился в PowerShell 3.0.

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

-Name

Указывает имя конфигурации сеанса, которую требуется изменить.

Этот параметр не может использоваться для изменения имени конфигурации сеанса.

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

-NoServiceRestart

Не перезапускает службу WinRM и подавляет запрос на перезапуск службы.

По умолчанию при запуске Set-PSSessionConfigurationвам будет предложено перезапустить службу WinRM , чтобы обеспечить эффективность новой конфигурации сеанса. Пока служба WinRM не будет перезапущена, новая конфигурация сеанса не будет эффективной.

Чтобы перезапустить службу WinRM без запроса, используйте параметр Force . Чтобы перезапустить службу WinRM вручную, используйте Restart-Service командлет .

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

-Path

Указывает путь к файлу конфигурации сеанса (.pssc), например файлу, созданному командлетом New-PSSessionConfigurationFile . Если путь не указан, по умолчанию используется текущий каталог.

Сведения об изменении файла конфигурации сеанса см. в разделе справки по командлету New-PSSessionConfigurationFile .

Этот параметр появился в PowerShell 3.0.

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

-PSVersion

Указывает версию PowerShell в сеансах, использующих эту конфигурацию сеанса.

Значение этого параметра имеет приоритет над значением ключа PowerShellVersion в файле конфигурации сеанса.

Этот параметр появился в PowerShell 3.0.

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

-RunAsCredential

Указывает учетные данные для команд в сеансе. По умолчанию команды выполняются с разрешениями текущего пользователя.

Этот параметр появился в PowerShell 3.0.

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

-SecurityDescriptorSddl

Задает другую строку SDDL для конфигурации.

Эта строка определяет разрешения, необходимые для использования новой конфигурации сеанса. Чтобы использовать конфигурацию сеанса в сеансе, пользователи должны иметь по крайней мере Execute(Invoke) разрешение на конфигурацию.

Чтобы использовать дескриптор безопасности по умолчанию для конфигурации, введите пустую строку ("") или значение $Null. По умолчанию используется корневой SDDL на WSMan: диске.

Если дескриптор безопасности является сложным, рассмотрите возможность использования параметра ShowSecurityDescriptorUI вместо этого. Использовать оба параметра в одной и той же команде нельзя.

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

-SessionTypeOption

Задает параметры конкретного типа для конфигурации сеанса. Введите объект параметров типа сеанса, например объект PSWorkflowExecutionOption , возвращаемый командлетом New-PSWorkflowExecutionOption .

Параметры сеансов, которые используют конфигурацию сеанса, определяется значениями параметров сеанса и параметров конфигурации сеанса. Если не указано, параметры, заданные в сеансе, например с помощью командлета New-PSSessionOption , имеют приоритет над параметрами, заданными в конфигурации сеанса. При этом значения параметров сеанса не могут превышать максимальные значения, заданные в конфигурации сеанса.

Этот параметр появился в PowerShell 3.0.

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

-ShowSecurityDescriptorUI

Указывает, что этот командлет является листом свойств, который помогает создать новый SDDL для конфигурации сеанса. Страница свойств появится после выполнения Set-PSSessionConfiguration команды и перезапуска службы WinRM .

При настройке разрешений для конфигурации следует помнить, что пользователи должны иметь по крайней мере Execute(Invoke) разрешение на использование конфигурации сеанса в сеансе.

Использовать этот параметр и параметр SecurityDescriptorSDDL в одной и той же команде нельзя.

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

-StartupScript

Указывает скрипт запуска для конфигурации. Введите полный путь к скрипту PowerShell. Указанный скрипт выполняется в новом сеансе, для которого используется данная конфигурация сеанса.

Чтобы удалить скрипт запуска из конфигурации сеанса, введите пустую строку ("") или значение $Null.

Для дальнейшей настройки пользовательского сеанса можно использовать скрипт запуска. Если скрипт создает ошибку, даже несрочную ошибку, сеанс не создается, а команда завершается ошибкой New-PSSession .

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

-ThreadApartmentState

Указывает состояние квартиры модуля потоков, который будет использоваться. Допустимы следующие значения:

• Unknown
• MTA
• STA

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

-ThreadOptions

Задает параметр параметров потока в конфигурации. Этот параметр определяет, как потоки создаются и используются при выполнении команды в сеансе. Допустимые значения для этого параметра:

• Default
• ReuseThread
• UseCurrentThread
• UseNewThread

Значение по умолчанию — UseCurrentThread.

Дополнительные сведения см. в разделе Перечисление 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

Задает параметры транспорта для конфигурации сеанса. Введите объект параметров транспорта, например объект WSManConfigurationOption , возвращаемый командлетом New-PSTransportOption .

Параметры сеансов, которые используют конфигурацию сеанса, определяется значениями параметров сеанса и параметров конфигурации сеанса. Если не указано, параметры, заданные в сеансе, например с помощью командлета New-PSSessionOption , имеют приоритет над параметрами, заданными в конфигурации сеанса. При этом значения параметров сеанса не могут превышать максимальные значения, заданные в конфигурации сеанса.

Этот параметр появился в PowerShell 3.0.

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

-UseSharedProcess

Используйте только один процесс для размещения всех сеансов, запущенных одним и тем же пользователем и использующих одну и ту же конфигурацию сеанса. По умолчанию каждый сеанс размещается в отдельном процессе.

Этот параметр появился в PowerShell 3.0.

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

-WhatIf

Показывает, что произойдет при запуске командлета. Командлет не выполняется.

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

Входные данные

None

В этот командлет нельзя передать входные данные.

Выходные данные

WSManConfigLeafElement

Примечания

Этот командлет доступен только на платформах Windows.

Чтобы выполнить этот командлет, запустите PowerShell с помощью параметра Запуск от имени администратора .

Командлет Set-PSSessionConfiguration не изменяет имя конфигурации, а поставщик WSMan не поддерживает командлет Rename-Item . Чтобы изменить имя конфигурации сеанса, используйте Unregister-PSSessionConfiguration командлет для удаления конфигурации, а затем используйте Register-PSSessionConfiguration командлет для создания и регистрации новой конфигурации сеанса.

С помощью командлета Set-PSSessionConfiguration можно изменить конфигурации по умолчанию Microsoft.PowerShell и Microsoft.PowerShell32 конфигурации сеанса. Они не защищены. Чтобы отменить изменения к исходной версии конфигурации сеанса по умолчанию, удалите конфигурацию сеанса по умолчанию с помощью Unregister-PSSessionConfiguration командлета Enable-PSRemoting , а затем используйте командлет для ее восстановления.

Свойства объекта конфигурации сеанса зависят от заданных для конфигурации сеанса параметров и значений этих параметров. Кроме того, конфигурации сеансов, определяющие с помощью файла конфигурации, включают дополнительные свойства.

Для изменения свойств конфигураций сеанса можно использовать команды на WSMan: диске. Однако диск в PowerShell 2.0 нельзя использовать WSMan: для изменения свойств конфигурации сеанса, представленных в PowerShell 3.0, например OutputBufferingMode. Команды Windows PowerShell 2.0 не вызывают ошибку, но они являются неэффективными. Чтобы изменить свойства, представленные в PowerShell 3.0, используйте WSMan: диск в PowerShell 3.0 или более поздней версии.

Связанные ссылки

• Disable-PSSessionConfiguration
• Enable-PSSessionConfiguration
• Get-PSSessionConfiguration
• New-PSSessionConfigurationFile
• New-PSSessionOption
• New-PSTransportOption
• Register-PSSessionConfiguration
• Test-PSSessionConfigurationFile
• Unregister-PSSessionConfiguration
• WSMan Provider
• about_Session_Configurations
• about_Session_Configuration_Files