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

Синтаксис

Register-PSSessionConfiguration [-AssemblyName] <string> [-ConfigurationTypeName] <string> [-ApplicationBase <string>] [-Name] <string> [-Force] [-MaximumReceivedDataSizePerCommandMB <double>] [-MaximumReceivedObjectSizeMB <double>] [-NoServiceRestart] [-ProcessorArchitecture <string>] [-SecurityDescriptorSDDL <string>] [-ShowSecurityDescriptorUI] [-StartupScript <string>] [-ThreadApartmentState {<STA> | <MTA> | <Unknown>}] [-ThreadOptions {<Default> | <UseNewThread> | <ReuseThread> | <UseCurrentThread>}] [-Confirm] [-WhatIf] [<CommonParameters>]

Описание

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

В каждом удаленном сеансе Windows PowerShell используется конфигурация сеанса. Создавая сеанс подключения к компьютеру, пользователи могут выбрать конфигурацию или использовать конфигурации по умолчанию, регистрируемые при включении удаленного взаимодействия Windows PowerShell. Пользователи также могут задавать привилегированную переменную $PSSessionConfigurationName, которая указывает конфигурацию по умолчанию для сеансов, создаваемых в текущем сеансе.

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

Параметры

-ApplicationBase <string>

Задает путь к файлу сборки (*.dll), указанному в значении параметра AssemblyName. Этот параметр следует использовать в случае, если значение параметра AssemblyName не включает путь. По умолчанию используется текущий каталог.

Обязательно?

false

Позиция?

named

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

Current directory

Принимать входные данные из конвейера?

false

Принимать подстановочные знаки?

false

-AssemblyName <string>

Задает имя файла сборки (*.dll), в котором определен тип конфигурации. Задать путь к DLL-файлу можно в этом параметре или в значении параметра ApplicationBase.

При задании параметра ConfigurationTypeName этот параметр является обязательным.

Обязательно?

true

Позиция?

2

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

нет

Принимать входные данные из конвейера?

false

Принимать подстановочные знаки?

false

-ConfigurationTypeName <string>

Задает полное имя типа Microsoft .NET Framework, используемого для этой конфигурации. Задаваемый тип должен реализовывать класс System.Management.Automation.Remoting.PSSessionConfiguration.

Для задания файла сборки (DLL), реализующего тип конфигурации, используйте параметры AssemblyName и AssemblyBase.

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

Если опустить этот параметр, для конфигурации сеанса используется класс DefaultRemotePowerShellConfiguration.

Обязательно?

true

Позиция?

3

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

System.Management.Automation.Remoting.PSSessionConfiguration

Принимать входные данные из конвейера?

false

Принимать подстановочные знаки?

false

-Force

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

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

Обязательно?

false

Позиция?

named

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

Принимать входные данные из конвейера?

false

Принимать подстановочные знаки?

false

-MaximumReceivedDataSizePerCommandMB <double>

Ограничивает объем данных, которые могут быть переданы данному компьютеру в любой отдельно взятой удаленной команде. Укажите объем данных в мегабайтах (МБ). По умолчанию используется значение "50 МБ".

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

Обязательно?

false

Позиция?

named

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

50

Принимать входные данные из конвейера?

false

Принимать подстановочные знаки?

false

-MaximumReceivedObjectSizeMB <double>

Ограничивает объем данных, которые могут быть переданы данному компьютеру в любом отдельно взятом объекте. Укажите объем данных в мегабайтах (МБ). По умолчанию используется значение "10 МБ".

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

Обязательно?

false

Позиция?

named

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

10

Принимать входные данные из конвейера?

false

Принимать подстановочные знаки?

false

-Name <string>

Задает имя конфигурации сеанса. Это обязательный параметр.

Обязательно?

true

Позиция?

1

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

нет

Принимать входные данные из конвейера?

false

Принимать подстановочные знаки?

false

-NoServiceRestart

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

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

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

Обязательно?

false

Позиция?

named

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

False

Принимать входные данные из конвейера?

false

Принимать подстановочные знаки?

false

-ProcessorArchitecture <string>

Задает архитектуру процессора для конфигурации. Это значение определяет, 32- или 64-разрядная версия хост-процесса Windows PowerShell запускается при использовании данной конфигурации. Допустимые значения: "x86", "AMD64" и "IA64".

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

Обязательно?

false

Позиция?

named

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

The processor architecture of the host computer.

Принимать входные данные из конвейера?

false

Принимать подстановочные знаки?

false

-SecurityDescriptorSDDL <string>

Задает строку в формате языка определения дескрипторов безопасности (SDDL) для конфигурации.

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

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

Если опустить этот параметр, для данной конфигурации будет использоваться корневой элемент SDDL для службы WinRM. Для просмотра или изменения корневого элемента SDDL используйте поставщик WS-Management. Например: "Get-Item wsman:\localhost\service\rootSDDL". Чтобы получить дополнительные сведения о поставщике WS-Management, введите команду "Get-Help wsman".

Обязательно?

false

Позиция?

named

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

The value of the root SDDL

Принимать входные данные из конвейера?

false

Принимать подстановочные знаки?

false

-ShowSecurityDescriptorUI

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

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

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

Обязательно?

false

Позиция?

named

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

Принимать входные данные из конвейера?

false

Принимать подстановочные знаки?

false

-StartupScript <string>

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

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

Обязательно?

false

Позиция?

named

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

Принимать входные данные из конвейера?

false

Принимать подстановочные знаки?

false

-ThreadApartmentState <ApartmentState>

Определяет состояние подразделения потоков в сеансе. Допустимые значения: "STA", "MTA" и "Unknown". По умолчанию используется значение "Unknown".

Обязательно?

false

Позиция?

named

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

Unknown

Принимать входные данные из конвейера?

false

Принимать подстановочные знаки?

false

-ThreadOptions <PSThreadOptions>

Определяет способ создания и использования потоков при выполнении команд в сеансе. Допустимые значения: "Default", "ReuseThread", "UseCurrentThread" и "UseNewThread". По умолчанию используется значение "UseCurrentThread".

Обязательно?

false

Позиция?

named

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

UseCurrentThread

Принимать входные данные из конвейера?

false

Принимать подстановочные знаки?

false

-Confirm

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

Обязательно?

false

Позиция?

named

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

Принимать входные данные из конвейера?

false

Принимать подстановочные знаки?

false

-WhatIf

Описывает, что произойдет при выполнении команды, без ее фактического выполнения.

Обязательно?

false

Позиция?

named

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

Принимать входные данные из конвейера?

false

Принимать подстановочные знаки?

false

<CommonParameters>

Данный командлет поддерживает общие параметры -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer и -OutVariable. Дополнительные сведения см. в разделе about_Commonparameters.

Ввод и вывод

Входным типом является тип объектов, которые можно передавать командлету по конвейеру. Возвращаемым типом является тип объектов, возвращаемых командлетом.

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

Нет

Передать входные данные этому командлету по конвейеру невозможно.

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

Microsoft.WSMan.Management.WSManConfigContainerElement

Примечания

Чтобы использовать этот командлет в Windows Vista, Windows Server 2008 и более поздних версиях Windows, необходимо запускать Windows PowerShell командой "Запуск от имени администратора".

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

Пример 1

C:\PS>register-pssessionConfiguration -name NewShell -applicationBase c:\MyShells\ -assemblyName MyShell.dll -configurationTypeName MyClass

Описание
-----------
Эта команда регистрирует новую конфигурацию сеанса NewShell. Параметры ApplicationName и ApplicationBase используются для указания местоположения файла MyShell.dll, который задает командлеты и поставщики в конфигурации сеанса. Кроме того, используется параметр ConfigurationTypeName для указания нового класса, используемого для дальнейшей настройки сеанса.

Для использования этой конфигурации пользователи должны будут ввести команду "new-pssession -configurationname newshell".






Пример 2

C:\PS>register-pssessionConfiguration -name MaintenanceShell -startupScript c:\ps-test\Maintenance.ps1

Описание
-----------
Эта команда регистрирует на локальном компьютере конфигурацию MaintenanceShell. Параметр StartupScript используется для указания скрипта Maintenance.ps1.

Когда пользователь вводит команду New-PSSession и выбирает конфигурацию MaintenanceShell, в новом сеансе выполняется скрипт Maintenance.ps1. Этот скрипт может настраивать сеанс, в том числе импортировать модули, добавлять оснастки Windows PowerShell и задавать политику выполнения для сеанса. Если скрипт выдаст какую-либо ошибку, в том числе непрерывающую, команда New-PSSession завершится неудачей.






Пример 3

C:\PS>$sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FA;SA;GWGX;;WD)"

C:\PS> register-pssessionconfiguration -name AdminShell -securityDescriptorSDDL $sddl -maximumReceivedObjectSizeMB 20 -startupScript c:\scripts\AdminShell.ps1

Описание
-----------
Этот пример регистрирует конфигурацию сеанса AdminShell. 

Первая команда сохраняет пользовательскую строку SDDL в переменной $sddl. 

Вторая команда регистрирует новую оболочку. В команде используется параметр SecurityDescritorSDDL для задания строки SDDL из переменной $sddl и параметр MaximumReceivedObjectSizeMB для увеличения ограничения на размер объекта. Кроме того, используется параметр StartupScript для указания скрипта, используемого для настройки параметра.

В качестве альтернативы параметру SecurityDescriptorSDDL можно использовать параметр ShowSecurityDescriptorUI для вывода листа свойств, с помощью которого можно будет задать разрешения для конфигурации сеанса. При нажатии кнопки "ОК" в листе свойств формируется строка SDDL для конфигурации сеанса.






Пример 4

C:\PS>$s = register-pssessionConfiguration -name MaintenanceShell -startupScript c:\ps-test\Maintenance.ps1

C:\PS> $s

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

Name					Type				 Keys
----					----				 ----
MaintenanceShell		Container			{Name=MaintenanceShell}


C:\PS> $s.getType().fullname
TypeName: Microsoft.WSMan.Management.WSManConfigContainerElement


C:\PS> $s | format-list -property *

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


C:\PS> dir wsman:\localhost\plugin

Name					Type				 Keys
----					----				 ----
MaintenanceShell		Container			{Name=MaintenanceShell}
microsoft.powershell	Container			{Name=microsoft.powershell}
microsoft.powershell32	Container			{Name=microsoft.powershell32}

Описание
-----------
Этот пример показывает, что команда Register-PSSessionConfiguration возвращает элемент WSManConfigContainerElement. Также в нем показано, как найти элементы-контейнеры на диске WSMan:.

Первая команда регистрирует конфигурацию сеанса MaintenanceShell с помощью командлета Register-PSSessionConfiguration. Она сохраняет объект, возвращенный командлетом, в переменной $s.

Вторая команда отображает содержимое переменной $s. 

Третья команда с помощью метода GetType и его свойства FullName отображает имя типа объекта, возвращенного командлетом Register-PSSessionConfiguration.

Четвертая команда с помощью командлета Format-List отображает все свойства объекта, возвращенного командлетом Register-PSSessionConfiguration, в виде списка. Из свойства PSPath видно, что объект хранится в каталоге на диске WSMan:.

Пятая команда с помощью командлета Get-ChildItem отображает элементы в папке WSMan:\LocalHost\PlugIn. В этой папке находится новая конфигурация MaintenanceShell и две конфигурации по умолчанию, входящие в комплект Windows PowerShell.






Пример 5

C:\PS>register-pssessionconfiguration -name WithProfile -startupScript add-profile.ps1

# Add-Profile.ps1

. c:\users\admin01\documents\windowspowershell\profile.ps1

Описание
-----------
Эта команда создает и регистрирует конфигурацию сеанса WithProfile на локальном компьютере. В ней используется параметр StartupScript, который дает Windows PowerShell указание выполнять указанный скрипт в любом сеансе, для которого используется данная конфигурация.

Также отображается содержимое указанного скрипта (Add-Profile.ps1). Скрипт содержит единственную команду, в которой используется запись с точками для запуска профиля CurrentUserAllHosts пользователя в текущей области сеанса.

Дополнительные сведения о профилях см. в разделе about_Profiles. Дополнительные сведения о записи с точками см. в разделе about_Scopes.






См. также