Register-PSSessionConfiguration

Синтаксис

NameParameterSet (по умолчанию)

Register-PSSessionConfiguration
    [-Name] <String>
    [-ProcessorArchitecture <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>]

AssemblyNameParameterSet

Register-PSSessionConfiguration
    [-Name] <String>
    [-AssemblyName] <String>
    [-ConfigurationTypeName] <String>
    [-ProcessorArchitecture <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>]

SessionConfigurationFile

Register-PSSessionConfiguration
    [-Name] <String>
    -Path <String>
    [-ProcessorArchitecture <String>]
    [-RunAsCredential <PSCredential>]
    [-ThreadApartmentState <ApartmentState>]
    [-ThreadOptions <PSThreadOptions>]
    [-AccessMode <PSSessionConfigurationAccessMode>]
    [-UseSharedProcess]
    [-StartupScript <String>]
    [-MaximumReceivedDataSizePerCommandMB <Double>]
    [-MaximumReceivedObjectSizeMB <Double>]
    [-SecurityDescriptorSddl <String>]
    [-ShowSecurityDescriptorUI]
    [-Force]
    [-NoServiceRestart]
    [-TransportOption <PSTransportOption>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Описание

Примеры

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

$sessionConfiguration = @{
    Name='NewShell'
    ApplicationBase='C:\MyShells\'
    AssemblyName='MyShell.dll'
    ConfigurationTypeName='MyClass'
}
Register-PSSessionConfiguration @sessionConfiguration

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

Register-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1

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

$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. Возврат элемента контейнера конфигурации

$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. Регистрация конфигурации сеанса с помощью скрипта запуска

Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.ps1

Параметры

-AccessMode

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

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

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

Другие командлеты могут переопределить значение этого параметра позже. Например, командлет Enable-PSRemoting разрешает удаленный доступ ко всем конфигурациям сеансов, командлет Enable-PSSessionConfiguration включает конфигурации сеансов, а командлет Disable-PSRemoting запрещает удаленный доступ ко всем конфигурациям сеансов.

Этот параметр появился в PowerShell 3.0.

Свойства параметра

Наборы параметров

-ApplicationBase

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

Свойства параметра

Наборы параметров

-AssemblyName

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

Этот параметр требуется при указании параметра ConfigurationTypeName.

Свойства параметра

Наборы параметров

-ConfigurationTypeName

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

Чтобы указать файл сборки (*.dll), реализующий тип конфигурации, укажите параметры assemblyName и ApplicationBase.

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

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

Свойства параметра

Наборы параметров

-Confirm

Запрашивает подтверждение перед запуском cmdlet.

Свойства параметра

Наборы параметров

-Force

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

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

Свойства параметра

Наборы параметров

-MaximumReceivedDataSizePerCommandMB

Указывает ограничение объема данных, которые можно отправить на этот компьютер в любой удаленной команде. Введите размер данных в мегабайтах (МБ). Значение по умолчанию — 50 МБ.

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

Свойства параметра

Наборы параметров

-MaximumReceivedObjectSizeMB

Задает ограничение объема данных, которые можно отправить на этот компьютер в любом одном объекте. Введите размер данных в мегабайтах. Значение по умолчанию — 10 МБ.

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

Свойства параметра

Наборы параметров

-ModulesToImport

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

По умолчанию в сеансы импортируется только Microsoft.PowerShell.Core. Если командлеты не исключены, можно использовать Import-Module для добавления модулей в сеанс.

Модули, указанные в этом значении параметра, импортируются в дополнение к модулям, указанным параметром SessionType и перечисленными в ключе ModulesToImport в файле конфигурации сеанса (New-PSSessionConfigurationFile). Однако параметры в файле конфигурации сеанса могут скрыть команды, экспортированные модулями, или запретить пользователям использовать их.

Этот параметр появился в PowerShell 3.0.

Свойства параметра

Наборы параметров

-Name

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

Свойства параметра

Наборы параметров

-NoServiceRestart

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

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

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

Эта функция реализована в PowerShell 7.5.0-preview.4.

Свойства параметра

Наборы параметров

-Path

Указывает путь и имя файла конфигурации сеанса (PSSC), например файл, созданный New-PSSessionConfigurationFile. Если вы опустите путь, по умолчанию используется текущий каталог.

Этот параметр появился в PowerShell 3.0.

Свойства параметра

Наборы параметров

-ProcessorArchitecture

Определяет, запущена ли 32-разрядная или 64-разрядная версия процесса PowerShell в сеансах, использующих эту конфигурацию сеанса. Допустимые значения для этого параметра: x86 (32-разрядная версия) и AMD64 (64-разрядная версия). Значение по умолчанию определяется архитектурой процессора компьютера, на котором размещена конфигурация сеанса.

Этот параметр можно использовать для создания 32-разрядного сеанса на 64-разрядном компьютере. Пытается создать 64-разрядный процесс на 32-разрядном компьютере.

Свойства параметра

Наборы параметров

-PSVersion

Указывает версию PowerShell в сеансах, использующих эту конфигурацию сеанса.

Значение этого параметра имеет приоритет над значением ключа PowerShellVersion в файле конфигурации сеанса.

Этот параметр появился в PowerShell 3.0.

Свойства параметра

Наборы параметров

-RunAsCredential

Задает учетные данные для команд в сеансе. По умолчанию команды выполняются с разрешениями текущего пользователя.

Этот параметр появился в PowerShell 3.0.

Свойства параметра

Наборы параметров

-SecurityDescriptorSddl

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

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

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

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

Свойства параметра

Наборы параметров

-SessionTypeOption

Задает параметры, относящиеся к типу для конфигурации сеанса. Введите объект параметров типа сеанса, например объект PSWorkflowExecutionOption, возвращаемый командлетом New-PSWorkflowExecutionOption.

Параметры сеансов, использующих конфигурацию сеанса, определяются значениями параметров сеанса и параметрами конфигурации сеанса. Если не указано, параметры, заданные в сеансе, например с помощью командлета New-PSSessionOption, имеют приоритет над параметрами, заданными в конфигурации сеанса. Однако значения параметров сеанса не могут превышать максимальные значения, заданные в конфигурации сеанса.

Этот параметр появился в PowerShell 3.0.

Свойства параметра

Наборы параметров

-ShowSecurityDescriptorUI

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

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

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

Свойства параметра

Наборы параметров

-StartupScript

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

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

Свойства параметра

Наборы параметров

-ThreadApartmentState

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

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

Свойства параметра

Наборы параметров

-ThreadOptions

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

• По умолчанию
• Повторное использованиеThread
• UseCurrentThread
• ИспользуйтеNewThread

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

Дополнительные сведения см. в перечисления PSThreadOptions.

Свойства параметра

Наборы параметров

-TransportOption

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

Этот параметр появился в PowerShell 3.0.

Свойства параметра

Наборы параметров

-UseSharedProcess

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

Этот параметр появился в PowerShell 3.0.

Свойства параметра

Наборы параметров

-WhatIf

Показывает, что произойдет, если командлет будет запущен. Командлет не выполняется.

Свойства параметра

Наборы параметров

CommonParameters

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

None

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

WSManConfigContainerElement

Примечания

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

• Disable-PSSessionConfiguration
• Enable-PSSessionConfiguration
• Get-PSSessionConfiguration
• New-PSSessionConfigurationFile
• Set-PSSessionConfiguration (Настройка сеанса PowerShell)
• Test-PSSessionConfigurationFile
• Unregister-PSSessionConfiguration
• Поставщик WSMan
• о_Конфигурациях_Сессии
• about_Session_Configuration_Files (о_файлах_настроек_сессии)