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

В этом примере регистрируется конфигурация сеанса 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

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

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

Значение по умолчанию — 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

-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

-ThreadApartmentState

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

Неизвестно
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

Задает параметр транспорта.

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

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

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

Примечания

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

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