Register-PSSessionConfiguration

Ссылка

Модуль:: Microsoft.PowerShell.Core

Создает и регистрирует новую конфигурацию сеанса.

Синтаксис

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. Регистрация конфигурации сеанса

В этом примере регистрируется конфигурация сеанса Администратор Shell.

Переменная $sessionParams — это хэш-файл, содержащий все значения параметров. Этот хэш-файл передается командлету с помощью различения PowerShell. Команда Register-PSSessionConfiguration использует параметр SecurityDescritorSDDL для указания SDDL в значении переменной $sddl и параметра MaximumReceivedObjectSize МБ для увеличения ограничения размера объекта. Параметр 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.

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) для конфигурации.

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

В случае сложного дескриптора безопасности вместо этого параметра можно использовать параметр 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

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

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

Использовать этот параметр и параметр 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

-ThreadApartmentState

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

Неизвестно
MTA
STA

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

-ThreadOptions

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

По умолчанию.
Повторное использованиеThread
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

Невозможно передать объекты в этот командлет.

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

WSManConfigContainerElement

Примечания

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

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

Этот командлет создает XML-файл, представляющий конфигурацию подключаемого модуля веб-служб управления (WS-Management) и отправляет XML-файл в WS-Management, который регистрирует подключаемый модуль на локальном компьютере (New-Item wsman:\localhost\plugin).

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

Register-PSSessionConfiguration

Синтаксис

Описание

Примеры

Пример 1. Регистрация конфигурации сеанса NewShell

Пример 2. Регистрация конфигурации сеанса MaintenanceShell

Пример 3. Регистрация конфигурации сеанса

Пример 4. Возврат элемента контейнера конфигурации

Пример 5. Регистрация конфигурации сеанса с помощью скрипта запуска

Параметры

-AccessMode

-ApplicationBase

-AssemblyName

-ConfigurationTypeName

-Confirm

-Force

-MaximumReceivedDataSizePerCommandMB

-MaximumReceivedObjectSizeMB

-ModulesToImport

-Name

-NoServiceRestart

-Path

-ProcessorArchitecture

-PSVersion

-RunAsCredential

-SecurityDescriptorSddl

-SessionTypeOption

-ShowSecurityDescriptorUI

-StartupScript

-ThreadApartmentState

-ThreadOptions

-TransportOption

-UseSharedProcess

-WhatIf

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

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

Примечания

Обратная связь

Дополнительные ресурсы

Register-PSSessionConfiguration

Синтаксис

Описание

Примеры

Пример 1. Регистрация конфигурации сеанса NewShell

Пример 2. Регистрация конфигурации сеанса MaintenanceShell

Пример 3. Регистрация конфигурации сеанса

Пример 4. Возврат элемента контейнера конфигурации

Пример 5. Регистрация конфигурации сеанса с помощью скрипта запуска

Параметры

-AccessMode

-ApplicationBase

-AssemblyName

-ConfigurationTypeName

-Confirm

-Force

-MaximumReceivedDataSizePerCommandMB

-MaximumReceivedObjectSizeMB

-ModulesToImport

-Name

-NoServiceRestart

-Path

-ProcessorArchitecture

-PSVersion

-RunAsCredential

-SecurityDescriptorSddl

-SessionTypeOption

-ShowSecurityDescriptorUI

-StartupScript

-ThreadApartmentState

-ThreadOptions

-TransportOption

-UseSharedProcess

-WhatIf

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

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

Примечания

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

Обратная связь

Дополнительные ресурсы