Register-PSSessionConfiguration
Создает и регистрирует новую конфигурацию сеанса.
Синтаксис
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>]
Описание
Этот командлет доступен только на платформе Windows.
Командлет 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;FASA;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
Включает и отключает конфигурацию сеанса и определяет возможность ее использования для удаленных или локальных сеансов компьютера. Допустимые значения для этого параметра:
- Disabled. отключает конфигурацию сеанса. Его нельзя использовать для удаленного или локального доступа к компьютеру.
- Локальный. Позволяет пользователям локального компьютера использовать конфигурацию сеанса для создания локального сеанса обратного цикла на том же компьютере, но запрещает доступ к удаленным пользователям.
- Удаленные. позволяет локальным и удаленным пользователям использовать конфигурацию сеанса для создания сеансов и выполнить команды на этом компьютере.
Значение по умолчанию — Remote.
Другие командлеты могут переопределить значение этого параметра позже. Например, Enable-PSRemoting
командлет позволяет удаленному доступу ко всем конфигурациям сеансов, Enable-PSSessionConfiguration
командлет включает конфигурации сеансов, а Disable-PSRemoting
командлет запрещает удаленный доступ ко всем конфигурациям сеанса.
Этот параметр появился в PowerShell 3.0.
Тип: | PSSessionConfigurationAccessMode |
Допустимые значения: | Disabled, Local, Remote |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-ApplicationBase
Указывает путь к файлу сборки (*.dll
), указанному в значении параметра AssemblyName . Используйте этот параметр, если значение параметра AssemblyName не содержит путь. По умолчанию используется текущий каталог.
Тип: | String |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-AssemblyName
Указывает имя файла сборки (*.dll), в котором определен тип конфигурации. Можно указать путь к .dll в этом параметре или в значении параметра ApplicationBase .
Этот параметр требуется при указании параметра ConfigurationTypeName .
Тип: | String |
Position: | 1 |
Default value: | None |
Обязательно: | True |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-ConfigurationTypeName
Указывает полное имя типа Microsoft платформа .NET Framework, используемого для этой конфигурации. Указанный тип должен реализовать класс System.Management.Automation.Remoting.PSSessionConfiguration.
Чтобы указать файл сборки (*.dll
), реализующий тип конфигурации, укажите параметры AssemblyName и ApplicationBase .
Создание типа позволяет управлять дополнительными аспектами конфигурации сеанса, такими как предоставление или скрытие определенных параметров командлетов, а также настройка ограничений размера данных и размеров объектов, которые пользователи не могут переопределить.
Если этот параметр не указан, для настройки конфигурации сеанса используется класс DefaultRemotePowerShellConfiguration.
Тип: | String |
Position: | 2 |
Default value: | None |
Обязательно: | True |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-Confirm
Запрос подтверждения перед выполнением командлета.
Тип: | SwitchParameter |
Aliases: | cf |
Position: | Named |
Default value: | False |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-Force
Подавляет все запросы пользователей и перезапускает службу WinRM без запроса. Перезапуск службы обеспечивает вступление изменений конфигурации в силу.
Чтобы предотвратить перезапуск и отключить запрос на перезапуск, укажите параметр NoServiceRestart .
Тип: | SwitchParameter |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-MaximumReceivedDataSizePerCommandMB
Указывает ограничение объема данных, которые можно отправить на этот компьютер в любой удаленной команде. Введите размер данных в мегабайтах (МБ). Значение по умолчанию — 50 МБ.
Если ограничение размера данных определено в типе конфигурации, указанном в параметре ConfigurationTypeName , используется ограничение в типе конфигурации, а значение этого параметра игнорируется.
Тип: | Nullable<T>[Double] |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-MaximumReceivedObjectSizeMB
Задает ограничение объема данных, которые можно отправить на этот компьютер в любом одном объекте. Введите размер данных в мегабайтах. Значение по умолчанию — 10 МБ.
Если ограничение размера объекта определено в типе конфигурации, указанном в параметре ConfigurationTypeName , используется ограничение в типе конфигурации, а значение этого параметра игнорируется.
Тип: | Nullable<T>[Double] |
Position: | Named |
Default value: | 10 |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-ModulesToImport
Указывает модули, которые автоматически импортируются в сеансы, использующие конфигурацию сеанса.
По умолчанию в сеансы импортируется только Microsoft.PowerShell.Core . Если командлеты не исключены, можно использовать Import-Module
для добавления модулей в сеанс.
Модули, указанные в этом значении параметра, импортируются в дополнение к модулям, указанным параметром SessionType, и теми, которые перечислены в ключе ModulesToImport в файле конфигурации сеанса (New-PSSessionConfigurationFile
). При этом параметры в файле конфигурации сеанса могут скрывать экспортируемые модулями команды или запрещать их использование.
Этот параметр появился в PowerShell 3.0.
Тип: | Object[] |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-Name
Указывает имя конфигурации сеанса. Этот параметр является обязательным.
Тип: | String |
Position: | 0 |
Default value: | None |
Обязательно: | True |
Принять входные данные конвейера: | True |
Принять подстановочные знаки: | False |
-NoServiceRestart
Целью этого параметра является предотвращение перезапуска службы WinRM . Эта функция еще не реализована.
Эта функция реализована в PowerShell 7.5.0-preview.4.
Тип: | SwitchParameter |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-Path
Указывает путь и имя файла конфигурации сеанса (PSSC), например файл, созданный New-PSSessionConfigurationFile
. Если путь не указан, по умолчанию используется текущий каталог.
Этот параметр появился в PowerShell 3.0.
Тип: | String |
Position: | Named |
Default value: | None |
Обязательно: | True |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-ProcessorArchitecture
Определяет, запущена ли 32-разрядная или 64-разрядная версия процесса PowerShell в сеансах, использующих эту конфигурацию сеанса. Допустимые значения для этого параметра: x86 (32-разрядная версия) и AMD64 (64-разрядная версия). Значение по умолчанию определяется архитектурой процессора компьютера, на котором размещена конфигурация сеанса.
Этот параметр можно использовать для создания 32-разрядного сеанса на 64-разрядном компьютере. Создать 64-разрядный процесс на 32-разрядном компьютере нельзя.
Тип: | String |
Aliases: | PA |
Допустимые значения: | x86, amd64 |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-PSVersion
Указывает версию PowerShell в сеансах, использующих эту конфигурацию сеанса.
Значение этого параметра имеет приоритет над значением ключа PowerShellVersion в файле конфигурации сеанса.
Этот параметр появился в PowerShell 3.0.
Тип: | Version |
Aliases: | PowerShellVersion |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-RunAsCredential
Задает учетные данные для команд в сеансе. По умолчанию команды выполняются с разрешениями текущего пользователя.
Этот параметр появился в PowerShell 3.0.
Тип: | PSCredential |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-SecurityDescriptorSddl
Задает строку в формате языка определения дескрипторов безопасности (SDDL) для конфигурации.
Эта строка определяет разрешения, необходимые для использования новой конфигурации сеанса. Чтобы использовать конфигурацию сеанса в сеансе, пользователи должны иметь по крайней мере разрешение execute (Invoke) для конфигурации.
В случае сложного дескриптора безопасности вместо этого параметра можно использовать параметр ShowSecurityDescriptorUI. В одной команде нельзя использовать оба параметра.
Если этот параметр не указан, для этой конфигурации используется корневой SDDL для службы WinRM .
Для просмотра или изменения корневого элемента SDDL используйте поставщик WS-Management. Например, Get-Item wsman:\localhost\service\rootSDDL
. Дополнительные сведения о поставщике WSMan введите Get-Help wsman
.
Тип: | String |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-SessionTypeOption
Задает параметры, относящиеся к типу для конфигурации сеанса. Введите объект параметров типа сеанса , например объект PSWorkflowExecutionOption , возвращаемый командлетом New-PSWorkflowExecutionOption
.
Параметры сеансов, которые используют конфигурацию сеанса, определяется значениями параметров сеанса и параметров конфигурации сеанса. Если не указано, параметры, заданные в сеансе, например с помощью командлета New-PSSessionOption
, имеют приоритет над параметрами, заданными в конфигурации сеанса. Однако значения параметров сеанса не могут превышать максимальные значения, заданные в конфигурации сеанса.
Этот параметр появился в PowerShell 3.0.
Тип: | PSSessionTypeOption |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-ShowSecurityDescriptorUI
Указывает, что этот командлет отображает лист свойств, который помогает создать SDDL для конфигурации сеанса. Лист свойств появится после ввода Register-PSSessionConfiguration
команды, а затем перезапустить службу WinRM .
При настройке разрешений для конфигурации помните, что у пользователей должно быть по крайней мере разрешение execute (Invoke) для использования конфигурации сеанса в сеансе.
Нельзя использовать параметр SecurityDescriptorSDDL и этот параметр в той же команде.
Тип: | SwitchParameter |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-StartupScript
Указывает полный путь к скрипту PowerShell. Указанный скрипт выполняется в новом сеансе, для которого используется данная конфигурация сеанса.
Скрипт можно использовать для дополнительной настройки сеанса. Если скрипт создает ошибку, даже не завершающаяся ошибка, сеанс не создается и команда завершается ошибкой New-PSSession
.
Тип: | String |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-ThreadApartmentState
Указывает состояние квартиры используемого модуля потоков. Допустимые значения:
- Неизвестно
- MTA
- STA
Тип: | ApartmentState |
Допустимые значения: | STA, MTA, Unknown |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-ThreadOptions
Указывает, как создаются и используются потоки при выполнении команды в сеансе. Допустимые значения для этого параметра:
- По умолчанию.
- Повторное использованиеThread
- UseCurrentThread
- UseNewThread
Значение по умолчанию — UseCurrentThread.
Дополнительные сведения см. в разделе перечисления PSThreadOptions.
Тип: | PSThreadOptions |
Допустимые значения: | Default, UseNewThread, ReuseThread, UseCurrentThread |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-TransportOption
Задает параметр транспорта.
Этот параметр появился в PowerShell 3.0.
Тип: | PSTransportOption |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-UseSharedProcess
Используйте для размещения всех сеансов, которые запускаются с одним и тем же именем пользователя и с одной и той же конфигурацией сеанса, только один процесс. По умолчанию каждый сеанс размещается в отдельном процессе.
Этот параметр появился в PowerShell 3.0.
Тип: | SwitchParameter |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-WhatIf
Показывает, что произойдет при запуске командлета. Командлет не выполняется.
Тип: | SwitchParameter |
Aliases: | wi |
Position: | Named |
Default value: | False |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
Входные данные
None
Невозможно передать объекты в этот командлет.
Выходные данные
Примечания
Этот командлет доступен только на платформах Windows.
Чтобы запустить этот командлет, необходимо запустить PowerShell с помощью параметра "Запуск от имени администратора ".
Этот командлет создает XML-файл, представляющий конфигурацию подключаемого модуля веб-служб управления (WS-Management) и отправляет XML-файл в WS-Management, который регистрирует подключаемый модуль на локальном компьютере (New-Item wsman:\localhost\plugin
).
Свойства объекта конфигурации сеанса зависят от заданных для конфигурации сеанса параметров и значений этих параметров. Кроме того, конфигурации сеансов, определяющие с помощью файла конфигурации, включают дополнительные свойства.
Связанные ссылки
PowerShell