Register-PSSessionConfiguration
Создает и регистрирует новую конфигурацию сеанса.
Синтаксис
Register-PSSessionConfiguration
[-ProcessorArchitecture <String>]
[-SessionType <PSSessionType>]
[-Name] <String>
[-ApplicationBase <String>]
[-RunAsCredential <PSCredential>]
[-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>]
[-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>]
[-ThreadOptions <PSThreadOptions>]
[-AccessMode <PSSessionConfigurationAccessMode>]
[-UseSharedProcess]
[-StartupScript <String>]
[-MaximumReceivedDataSizePerCommandMB <Double>]
[-MaximumReceivedObjectSizeMB <Double>]
[-SecurityDescriptorSddl <String>]
[-ShowSecurityDescriptorUI]
[-Force]
[-NoServiceRestart]
[-TransportOption <PSTransportOption>]
-Path <String>
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Описание
Командлет Register-PSSessionConfiguration
создает и регистрирует новую конфигурацию сеанса на локальном компьютере. Это расширенный командлет, который можно использовать для создания пользовательских сеансов для удаленных пользователей.
Каждый сеанс PowerShell (PSSession) использует конфигурацию сеанса, также называемую конечной точкой. Когда пользователи создают сеанс, который подключается к компьютеру, они могут выбрать конфигурацию сеанса или использовать конфигурацию сеанса по умолчанию, которая регистрируется при включении удаленного взаимодействия PowerShell. Кроме того, пользователи могут задавать привилегированную переменную $PSSessionConfigurationName, которая определяет конфигурацию по умолчанию для удаленных сеансов, создаваемых в текущем сеансе.
Конфигурация сеанса определяет среду для удаленного сеанса. Она определяет, какие команды и элементы языка будут доступны в сеансе, и может включать параметры для защиты компьютера, например ограничения на объем данных, принимаемых сеансом в удаленном режиме в одном объекте или команде. Дескриптор безопасности конфигурации сеанса определяет, какие пользователи имеют разрешение на использование конфигурации сеанса.
Элементы конфигурации определяются с помощью сборки, реализующей новый класс конфигурации, или скрипта, выполняемого в сеансе. Начиная с PowerShell 3.0, вы также можете использовать файл конфигурации сеанса для определения конфигурации сеанса.
Сведения о конфигурациях сеансов см. в разделе about_Session_Configurations. Сведения о файлах конфигурации сеанса см. в разделе about_Session_Configuration_Files.
Примеры
Пример 1. Регистрация конфигурации сеанса NewShell
В этом примере мы регистрируем конфигурацию сеанса NewShell . Параметры AssemblyName и ApplicationBase указывают расположение файла MyShell.dll , который указывает командлеты и поставщики в конфигурации сеанса. Параметр ConfigurationTypeName указывает класс конфигурации для использования из сборки.
$sessionConfiguration = @{
Name='NewShell'
ApplicationBase='c:\MyShells\'
AssemblyName='MyShell.dll'
ConfigurationTypeName='MyClass'
}
Register-PSSessionConfiguration @sessionConfiguration
Чтобы использовать эту конфигурацию, введите New-PSSession -ConfigurationName newshell
.
Пример 2. Регистрация конфигурации сеанса MaintenanceShell
В этом примере регистрируется конфигурация сеанса MaintenanceShell на локальном компьютере. Параметр StartupScript указывает Maintenance.ps1
скрипт.
Register-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1
Когда пользователь использует New-PSSession
команду и выбирает конфигурацию MaintenanceShell , Maintenance.ps1
скрипт выполняется в новом сеансе. Скрипт может настроить сеанс. Сюда входит импорт модулей и настройка политики выполнения для сеанса. Если скрипт создает ошибки, в том числе неустранимые, команда завершается ошибкой New-PSSession
.
Пример 3. Регистрация конфигурации сеанса
В этом примере регистрируется конфигурация сеанса AdminShell .
Переменная $sessionParams
представляет собой хэш-таблицы, содержащую все значения параметров. Эта хэш-сводка передается командлету с помощью сплаттинга PowerShell. Команда Register-PSSessionConfiguration
использует параметр SecurityDescritorSDDL , чтобы указать SDDL в значении переменной $sddl
и параметр MaximumReceivedObjectSizeMB для увеличения ограничения на размер объекта. Параметр StartupScript определяет скрипт, который будет использоваться для настройки сеанса.
$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
Пример 4. Возврат элемента контейнера конфигурации
В этом примере показано, как зарегистрировать конфигурацию MaintenanceShell .
Register-PSSessionConfiguration
возвращает объект WSManConfigContainerElement , хранящийся в переменной $s
. Format-List
отображает все свойства возвращаемого объекта. Свойство PSPath показывает, что объект хранится в каталоге на диске WSMan:. Get-ChildItem
(псевдоним ) dir
отображает элементы в WSMan:\LocalHost\PlugIn
пути. К ним относятся новая конфигурация MaintenanceShell и две конфигурации по умолчанию, которые поставляются с 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}
Пример 5. Регистрация конфигурации сеанса с помощью скрипта запуска
В этом примере мы создадим и регистрируем конфигурацию сеанса WithProfile . Параметр StartupScript указывает PowerShell на выполнение указанного скрипта для любого сеанса, использующего конфигурацию сеанса.
Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.ps1
Скрипт содержит единственную команду, в которой используется запись с точками для запуска профиля CurrentUserAllHosts пользователя в текущей области сеанса.
Дополнительные сведения о профилях см. в разделе about_Profiles. Дополнительные сведения о вызовах с использованием точки см. в разделе about_Scopes.
Параметры
-AccessMode
Включает и отключает конфигурацию сеанса и определяет возможность ее использования для удаленных или локальных сеансов компьютера. Допустимые значения для этого параметра:
- Отключено. отключает конфигурацию сеанса. Использовать конфигурацию для локального или удаленного доступа к компьютеру.
- Локальный. Позволяет пользователям локального компьютера использовать конфигурацию сеанса для создания локального сеанса замыкания на себя на том же компьютере, но запрещает доступ удаленным пользователям.
- Удаленные. позволяет локальным и удаленным пользователям использовать конфигурацию сеанса для создания сеансов и выполнить команды на этом компьютере.
Значение по умолчанию — Remote.
Другие командлеты могут переопределить значение этого параметра позже. Например, Enable-PSRemoting
командлет разрешает удаленный доступ ко всем конфигурациям сеанса, Enable-PSSessionConfiguration
он включает конфигурации сеансов, а 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 . Используйте этот параметр, если значение параметра AssemblyName не содержит путь. Значением по умолчанию является текущий каталог.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-AssemblyName
Указывает имя файла сборки (*.dll), в котором определен тип конфигурации. Путь к .dll можно указать в этом параметре или в значении параметра ApplicationBase .
Этот параметр является обязательным при указании параметра ConfigurationTypeName .
Type: | String |
Position: | 1 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ConfigurationTypeName
задает полное имя типа Microsoft .NET Framework, используемого для этой конфигурации. Задаваемый тип должен реализовывать класс System.Management.Automation.Remoting.PSSessionConfiguration.
Чтобы указать файл сборки (*.dll), реализующий тип конфигурации, укажите параметры AssemblyName и ApplicationBase .
Создание типа позволяет управлять дополнительными аспектами конфигурации сеанса, такими как предоставление или скрытие определенных параметров командлетов, установка ограничений на размер данных и объектов, которые пользователи не могут переопределить.
Если этот параметр не указан, для настройки конфигурации сеанса используется класс DefaultRemotePowerShellConfiguration.
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: | 10 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ModulesToImport
Указывает модули, которые автоматически импортируются в сеансы, использующие конфигурацию сеанса.
По умолчанию в сеансы импортируется только Microsoft.PowerShell.Core . Если командлеты не исключены, можно использовать для Import-Module
добавления модулей в сеанс.
Модули, указанные в этом значении параметра, импортируются в дополнение к модулям, заданным параметром SessionType и перечисленным в разделе ModulesToImport в файле конфигурации сеанса (New-PSSessionConfigurationFile
). При этом параметры в файле конфигурации сеанса могут скрывать экспортируемые модулями команды или запрещать их использование.
Этот параметр появился в 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 и подавляет запрос на перезапуск службы.
По умолчанию при выполнении Register-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
Если путь не указан, по умолчанию используется текущий каталог.
Этот параметр появился в PowerShell 3.0.
Type: | String |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProcessorArchitecture
Определяет, запускается ли 32-разрядная или 64-разрядная версия процесса PowerShell в сеансах, использующих эту конфигурацию сеанса. Допустимые значения для этого параметра: x86 (32-разрядная версия) и AMD64 (64-разрядная версия). Значение по умолчанию определяется архитектурой процессора компьютера, на котором размещена конфигурация сеанса.
Этот параметр можно использовать для создания 32-разрядного сеанса на 64-разрядном компьютере. Создать 64-разрядный процесс на 32-разрядном компьютере нельзя.
Type: | String |
Aliases: | PA |
Accepted values: | x86, amd64 |
Position: | Named |
Default value: | None |
Required: | False |
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) для конфигурации.
Эта строка определяет разрешения, необходимые для использования новой конфигурации сеанса. Чтобы использовать конфигурацию сеанса в сеансе, пользователи должны иметь по крайней мере разрешение на выполнение (вызов) для конфигурации.
В случае сложного дескриптора безопасности вместо этого параметра можно использовать параметр ShowSecurityDescriptorUI. Использовать оба параметра в одной команде нельзя. Использовать оба параметра в одной и той же команде нельзя.
Если этот параметр не указан, для этой конфигурации будет использоваться корневой SDDL для службы WinRM .
Для просмотра или изменения корневого элемента SDDL используйте поставщик WS-Management. Например, Get-Item wsman:\localhost\service\rootSDDL
. Чтобы получить дополнительные сведения о поставщике WSMan, введите Get-Help wsman
.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SessionType
Указывает тип сеанса, создаваемого при использовании конфигурации сеанса. Допустимые значения для этого параметра:
- Пустой. Модули не добавляются в сеанс по умолчанию. Параметры этого командлета позволяют добавить в сеанс модули, функции, скрипты и другие элементы.
- По умолчанию. Добавляет Microsoft.PowerShell.Core в сеанс. Этот модуль включает
Import-Module
командлет, который пользователи могут использовать для импорта других модулей, если вы явно не запретите командлет. - RestrictedRemoteServer. Включает только следующие командлеты:
Exit-PSSession
,Get-Command
,Get-FormatData
,Get-Help
,Measure-Object
, ,Out-Default
иSelect-Object
. Скрипт, сборку и ключи в файле конфигурации сеанса для добавления позволяют добавлять в сеанс модули, функции, скрипты и другие элементы.
Значение по умолчанию — Default.
Значение этого параметра имеет приоритет над значением ключа SessionType в файле конфигурации сеанса.
Этот параметр появился в PowerShell 3.0.
Type: | PSSessionType |
Accepted values: | DefaultRemoteShell, Workflow |
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 для конфигурации сеанса. Страница свойств появится после ввода Register-PSSessionConfiguration
команды и перезапуска службы WinRM .
При настройке разрешений для конфигурации следует помнить, что пользователи должны иметь по крайней мере разрешение на выполнение (вызов) для использования конфигурации сеанса в сеансе.
Использовать этот параметр и параметр SecurityDescriptorSDDL в одной и той же команде нельзя.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-StartupScript
Указывает полный путь к скрипту PowerShell. Указанный скрипт выполняется в новом сеансе, для которого используется данная конфигурация сеанса.
Вы можете использовать скрипт для дополнительной настройки сеанса. Если скрипт создает ошибку, даже несрочную ошибку, сеанс не создается, а команда завершается ошибкой New-PSSession
.
Type: | String |
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
Задает параметр транспорта.
Этот параметр появился в 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
В этот командлет нельзя передать входные данные.
Выходные данные
Примечания
Этот командлет доступен только на платформах Windows.
Для выполнения этого командлета необходимо запустить PowerShell с помощью параметра Запуск от имени администратора .
Этот командлет создает XML-код, представляющий конфигурацию подключаемого модуля веб-служб для управления (WS-Management), и отправляет XML-код в WS-Management, который регистрирует подключаемый модуль на локальном компьютере (New-Item wsman:\localhost\plugin
).
Свойства объекта конфигурации сеанса зависят от заданных для конфигурации сеанса параметров и значений этих параметров. Кроме того, конфигурации сеансов, определяющие с помощью файла конфигурации, включают дополнительные свойства.