New-PSSessionOption
Создает объект, содержащий дополнительные параметры для сеанса PSSession.
Синтаксис
New-PSSessionOption
[-MaximumRedirection <Int32>]
[-NoCompression]
[-NoMachineProfile]
[-Culture <CultureInfo>]
[-UICulture <CultureInfo>]
[-MaximumReceivedDataSizePerCommand <Int32>]
[-MaximumReceivedObjectSize <Int32>]
[-OutputBufferingMode <OutputBufferingMode>]
[-MaxConnectionRetryCount <Int32>]
[-ApplicationArguments <PSPrimitiveDictionary>]
[-OpenTimeout <Int32>]
[-CancelTimeout <Int32>]
[-IdleTimeout <Int32>]
[-ProxyAccessType <ProxyAccessType>]
[-ProxyAuthentication <AuthenticationMechanism>]
[-ProxyCredential <PSCredential>]
[-SkipCACheck]
[-SkipCNCheck]
[-SkipRevocationCheck]
[-OperationTimeout <Int32>]
[-NoEncryption]
[-UseUTF16]
[-IncludePortInSPN]
[<CommonParameters>]
Описание
Командлет New-PSSessionOption
создает объект , содержащий дополнительные параметры для сеанса, управляемого пользователем (PSSession). Объект можно использовать в качестве значения параметра SessionOption командлетов, создающих PSSession, таких как New-PSSession
, Enter-PSSession
и Invoke-Command
.
Без параметров создает объект , New-PSSessionOption
содержащий значения по умолчанию для всех параметров. Поскольку все свойства доступны для изменения, вы можете использовать итоговый объект в качестве шаблона и создавать стандартные объекты параметров для своей организации.
Можно также сохранить объект параметра сеанса в переменной $PSSessionOption
предпочтения. Значения этой переменной устанавливают новые значения по умолчанию для параметров сеанса. Они действительны, если для сеанса не задано никаких параметров, и имеют приоритет над параметрами, заданными в конфигурации сеанса, однако их можно переопределить, указав параметры сеанса или объект параметров сеанса в командлете, создающем сеанс. Дополнительные сведения о переменной предпочтения см. в $PSSessionOption
разделе about_Preference_Variables.
При использовании объекта параметров сеанса в командлете, создающем сеанс, значения параметров сеанса имеют приоритет над значениями по умолчанию, заданными в привилегированной переменной $PSSessionOption и в конфигурации сеанса. Однако они не имеют приоритет над максимальными значениями, квотами и ограничениями, заданными в конфигурации сеанса. Дополнительные сведения о конфигурациях сеансов см. в разделе about_Session_Configurations.
Примеры
Пример 1. Create параметр сеанса по умолчанию
Эта команда создает объект параметра сеанса со всеми значениями по умолчанию.
New-PSSessionOption
MaximumConnectionRedirectionCount : 5
NoCompression : False
NoMachineProfile : False
ProxyAccessType : IEConfig
ProxyAuthentication : Negotiate
ProxyCredential :
SkipCACheck : False
SkipCNCheck : False
SkipRevocationCheck : False
OperationTimeout : 00:03:00
NoEncryption : False
UseUTF16 : False
Culture :
UICulture :
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize :
ApplicationArguments :
OpenTimeout : 00:03:00
CancelTimeout : 00:01:00
IdleTimeout : 00:04:00
Пример 2. Настройка сеанса с помощью объекта параметра сеанса
В этом примере показано, как использовать объект параметров сеанса для настройки сеанса.
$pso = New-PSSessionOption -Culture "fr-fr" -MaximumReceivedObjectSize 10MB
New-PSSession -ComputerName Server01 -SessionOption $pso
Первая команда создает новый объект параметра сеанса и сохраняет его в значении переменной $pso
. Вторая команда использует New-PSSession
командлет для создания сеанса на удаленном компьютере Server01. Команда использует объект параметра сеанса в значении переменной $pso
в качестве значения параметра SessionOption команды.
Пример 3. Запуск интерактивного сеанса
Эта команда использует Enter-PSSession
командлет для запуска интерактивного сеанса с компьютером Server01.
Enter-PSSession -ComputerName Server01 -SessionOption (New-PSSessionOption -NoEncryption -NoCompression)
Значение параметра SessionOption — это New-PSSessionOption
команда с параметрами NoEncryption и NoCompression .
Команда New-PSSessionOption
заключена в круглые скобки, чтобы убедиться, что она выполняется перед командой Enter-PSSession
.
Пример 4. Изменение объекта параметра сеанса
В этом примере показано, что можно изменить объект параметра сеанса. Все свойства имеют значения для чтения и записи.
$a = New-PSSessionOption
$a.OpenTimeout
Days : 0
Hours : 0
Minutes : 3
Seconds : 0
Milliseconds : 0
Ticks : 1800000000
TotalDays : 0.00208333333333333
TotalHours : 0.05
TotalMinutes : 3
TotalSeconds : 180
TotalMilliseconds : 180000
$a.UICulture = (Get-UICulture)
$a.OpenTimeout = (New-Timespan -Minutes 4)
$a.MaximumConnectionRedirectionCount = 1
$a
MaximumConnectionRedirectionCount : 1
NoCompression : False
NoMachineProfile : False
ProxyAccessType : IEConfig
ProxyAuthentication : Negotiate
ProxyCredential :
SkipCACheck : False
SkipCNCheck : False
SkipRevocationCheck : False
OperationTimeout : 00:03:00
NoEncryption : False
UseUTF16 : False
Culture :
UICulture : en-US
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize :
ApplicationArguments :
OpenTimeout : 00:04:00
CancelTimeout : 00:01:00
IdleTimeout : 00:04:00
Используйте этот метод для создания стандартного объекта сеанса в своей организации, а затем настраивайте отдельные его версии для определенных целей.
Пример 5. Create переменной предпочтения
Эта команда создает переменную $PSSessionOption
предпочтения.
$PSSessionOption = New-PSSessionOption -OpenTimeOut 120000
$PSSessionOption
Когда переменная предпочтения возникает в сеансе, она устанавливает значения по умолчанию для параметров в сеансах, созданных с помощью New-PSSession
командлетов , Enter-PSSession
и Invoke-Command
.
Чтобы сделать переменную доступной $PSSessionOption
во всех сеансах, добавьте ее в сеанс PowerShell и в профиль PowerShell.
Дополнительные сведения о переменной предпочтения см. в $PSSessionOption
разделе about_Preference_Variables.
Дополнительные сведения о профилях см. в разделе about_Profiles.
Пример 6. Выполнение требований для конфигурации удаленного сеанса
В этом примере показано, как использовать объект SessionOption для удовлетворения требований, предъявляемых к конфигурации удаленного сеанса.
$skipCN = New-PSSessionOption -SkipCNCheck
New-PSSession -ComputerName 171.09.21.207 -UseSSL -Credential Domain01\User01 -SessionOption $SkipCN
Первая команда использует New-PSSessionOption
командлет для создания объекта параметра сеанса со свойством SkipCNCheck . Команда сохраняет результирующий объект сеанса в переменной $skipCN
.
Вторая команда использует New-PSSession
командлет для создания нового сеанса на удаленном компьютере. Переменная $skipCN
проверка используется в значении параметра SessionOption.
Так как компьютер идентифицируется по его IP-адресу, значение параметра ComputerName не соответствует ни одному из общих имен в сертификате, который используется для SSL. По этой причине параметр SkipCNCheck является обязательным.
Пример 7. Предоставление аргументов для удаленного сеанса
В этом примере показано, как использовать параметр ApplicationArguments командлета New-PSSessionOption
, чтобы сделать дополнительные данные доступными для удаленного сеанса.
$team = @{Team="IT"; Use="Testing"}
$TeamOption = New-PSSessionOption -ApplicationArguments $team
$s = New-PSSession -ComputerName Server01 -SessionOption $TeamOption
Invoke-Command -Session $s {$PSSenderInfo.ApplicationArguments}
Name Value
---- -----
Team IT
Use Testing
PSVersionTable {CLRVersion, BuildVersion, PSVersion, WSManStackVersion...}
Invoke-Command -Session $s {
if ($PSSenderInfo.ApplicationArguments.Use -ne "Testing") {
.\logFiles.ps1
}
else {
"Just testing."
}
}
Just testing.
Первая команда создает хэш-таблицу с двумя ключами: Team и Use. Команда сохраняет хэш-таблицу в переменной $team
. Дополнительные сведения о хэш-таблицах см. здесь.
New-PSSessionOption
Затем командлет, используя параметр ApplicationArguments, создает объект параметра сеанса, сохраненный в переменной $team
. При New-PSSessionOption
создании объекта параметра сеанса он автоматически преобразует хэш-таблицу в значении параметра ApplicationArguments в примитивный словарь, чтобы данные можно было надежно передавать в удаленный сеанс.
Командлет New-PSSession
запускает сеанс на компьютере Server01. Параметр SessionOption используется для включения параметров в переменную $teamOption
.
Командлет Invoke-Command
демонстрирует, что данные в переменной $team
доступны для команд в удаленном сеансе. Данные отображаются в свойстве ApplicationArguments автоматической переменной $PSSenderInfo
.
В заключительной Invoke-Command
части показано, как можно использовать данные.
Параметры
-ApplicationArguments
Указывает словарь примитивов, отправляемый в удаленный сеанс. Команды и скрипты в удаленном сеансе, включая скрипты запуска в конфигурации сеанса, могут находить этот словарь в свойстве ApplicationArguments автоматической переменной $PSSenderInfo
. Этот параметр можно использовать для отправки данных в удаленный сеанс.
Дополнительные сведения см. в разделе about_Hash_Tables, about_Session_Configurations и about_Automatic_Variables.
Type: | PSPrimitiveDictionary |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CancelTimeout
Определяет, как долго PowerShell ожидает завершения операции отмены (CTRL+C) перед ее завершением. Введите значение в миллисекундах.
Значение по умолчанию — 60 000 (одна минута). Значение 0 (ноль) означает отсутствие времени ожидания; команда будет продолжать выполняться неопределенно долго.
Type: | Int32 |
Aliases: | CancelTimeoutMSec |
Position: | Named |
Default value: | 60000 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Culture
Указывает язык и региональные параметры, используемые для сеанса. Введите имя языка и региональных параметров в <languagecode2>-<country/regioncode2>
формате (например ja-JP
, ), переменную, содержащую объект CultureInfo , или команду, которая получает объект CultureInfo .
Значение по умолчанию — $Null
, а язык и региональные параметры, заданные в операционной системе, используются в сеансе.
Type: | CultureInfo |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-IdleTimeout
Определяет, как долго сеанс остается открытым, если удаленный компьютер не получает никакого обмена данными с локального компьютера. Сюда входит сигнал пульса. По истечении этого времени сеанс закрывается.
Значение времени ожидания простоя имеет важное значение, если вы планируете отключиться и повторно подключиться к сеансу. Повторно подключиться можно только в том случае, если не истекло время ожидания сеанса.
Введите значение в миллисекундах. Минимальное значение — 60 000 (1 минута). Максимальное значение задано свойством MaxIdleTimeoutms конфигурации сеанса. Значение по умолчанию -1 не устанавливает время ожидания простоя.
Сеанс использует время ожидания простоя, заданное в параметрах сеанса, если таковое имеется. Если значение не задано (-1), сеанс использует значение свойства IdleTimeoutMs конфигурации сеанса или значение времени ожидания оболочки WSMan (WSMan:\<ComputerName>\Shell\IdleTimeout
), в зависимости от того, какое значение является самым коротким.
Если заданное в параметрах сеанса время ожидания простоя превышает значение свойства MaxIdleTimeoutMs в конфигурации сеанса, команда создания сеанса завершается с ошибкой.
Значение IdleTimeoutMs конфигурации сеанса Microsoft.PowerShell по умолчанию равно 7200000 миллисекундам (2 часа). Его значение MaxIdleTimeoutMs равно 2147483647 миллисекундам (>24 дня). Значение по умолчанию для времени ожидания простоя оболочки WSMan (WSMan:\<ComputerName>\Shell\IdleTimeout
) равно 7200000 миллисекундам (2 часа).
Значение времени ожидания простоя сеанса также можно изменить при отключении от сеанса или повторном подключении к сеансу. Дополнительные сведения см. в разделах Disconnect-PSSession
и Connect-PSSession
.
В Windows PowerShell 2.0 значение по умолчанию для параметра IdleTimeout равно 240 000 (4 минуты).
Type: | Int32 |
Aliases: | IdleTimeoutMSec |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-IncludePortInSPN
Включает номер порта в имя субъекта-службы (SPN), используемое для проверки подлинности Kerberos, например HTTP://<ComputerName>:5985
. Этот параметр позволяет клиенту, который использует имя субъекта-службы, отличное от значения по умолчанию, выполнять аутентификацию для удаленного компьютера, который использует аутентификацию Kerberos.
Параметр предназначен для организаций, где несколько служб, поддерживающих аутентификацию Kerberos, выполняются с использованием разных учетных записей пользователей. Например, приложение IIS, которое допускает проверку подлинности Kerberos, может требовать регистрации имени субъекта-службы по умолчанию в учетной записи пользователя, которая отличается от учетной записи компьютера. В таких случаях удаленное взаимодействие PowerShell не может использовать Kerberos для проверки подлинности, так как для этого требуется имя субъекта-службы, зарегистрированное в учетной записи компьютера. Чтобы устранить эту проблему, администраторы могут создавать разные имена субъектов-служб, например с помощьюSetspn.exe, которые зарегистрированы в разных учетных записях пользователей и могут различать их, включив номер порта в имя субъекта-службы.
Дополнительные сведения см. в разделе Общие сведения о Setspn.
Этот параметр впервые появился в Windows PowerShell 3.0.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaxConnectionRetryCount
Указывает количество попыток подключения PowerShell к целевому компьютеру, если текущая попытка завершается неудачей из-за проблем с сетью. Значение по умолчанию — 5.
Этот параметр был добавлен для PowerShell версии 5.0.
Type: | Int32 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumReceivedDataSizePerCommand
Указывает максимальное число байтов, которые может получить локальный компьютер с удаленного компьютера в рамках одной команды. Введите значение в байтах. По умолчанию ограничения размера данных отсутствуют.
Этот параметр предназначен для защиты ресурсов на клиентском компьютере.
Type: | Int32 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumReceivedObjectSize
Указывает максимальный размер объекта, который может получить локальный компьютер с удаленного компьютера. Этот параметр предназначен для защиты ресурсов на клиентском компьютере. Введите значение в байтах.
Если пропустить этот параметр в Windows PowerShell 2.0, ограничение на размер объекта не действует. Начиная с Windows PowerShell 3.0, при отсутствии этого параметра применяется значение по умолчанию — 200 МБ.
Type: | Int32 |
Position: | Named |
Default value: | 200 MB |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumRedirection
Определяет, сколько раз PowerShell перенаправляет подключение на альтернативный универсальный код ресурса (URI) до сбоя подключения. Значение по умолчанию — 5. Значение 0 (ноль) запрещает любые перенаправления.
Этот параметр используется в сеансе, только если параметр AllowRedirection используется в команде, создающей сеанс.
Type: | Int32 |
Position: | Named |
Default value: | 5 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-NoCompression
Отключает сжатие пакетов в сеансе. Сжатие требует большего числа рабочих циклов процессора, но ускоряет передачу.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-NoEncryption
Отключает шифрование данных.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-NoMachineProfile
Запрещает загрузку профиля пользователя Windows. В результате сеанс может создаваться быстрее, но в нем будут недоступны параметры реестра для конкретного пользователя, элементы, такие как переменные среды, и сертификаты.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-OpenTimeout
Определяет время ожидания клиентского компьютера при установлении соединения сеанса. По истечении периода команда для установления соединения завершается с ошибкой. Введите значение в миллисекундах.
Значение по умолчанию — 180 000 (3 минуты). Значение 0 (ноль) означает отсутствие времени ожидания; команда будет продолжать выполняться неопределенно долго.
Type: | Int32 |
Aliases: | OpenTimeoutMSec |
Position: | Named |
Default value: | 180000 (3 minutes) |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-OperationTimeout
Определяет максимальное время выполнения любой операции в сеансе. По истечении периода операция завершается с ошибкой. Введите значение в миллисекундах.
Значение по умолчанию — 180 000 (3 минуты). Значение 0 (ноль) означает отсутствие времени ожидания; операция будет продолжать выполняться неопределенно долго.
Type: | Int32 |
Aliases: | OperationTimeoutMSec |
Position: | Named |
Default value: | 180000 (3 minutes) |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-OutputBufferingMode
Определяет порядок управления выходным потоком команды в отключенных сеансах при заполнении .
Если в сеансе или его конфигурации не задан режим буферизации выходных данных, используется значение по умолчанию Block. Пользователи также могут изменять режим буферизации выходных данных при отключении сеанса.
Если опустить этот параметр, значение OutputBufferingMode объекта параметра сеанса равно None. Значение Block или Drop переопределяет параметр режим буферизации выходных данных, заданный в конфигурации сеанса. Допустимые значения для этого параметра:
- Блокировка. при заполнении выходного буфера выполнение команды приостанавливается до тех пор, пока буфер не будет очищен.
- Drop. при заполнении выходного буфера выполнение команды продолжается. Новые выходные данные сохраняются вместо наиболее старых.
- Нет. порядок действий в случае переполнения выходного буфера не установлен.
Дополнительные сведения о параметре транспорта режима буферизации вывода см. в разделе New-PSTransportOption
.
Этот параметр впервые появился в Windows PowerShell 3.0.
Type: | OutputBufferingMode |
Accepted values: | None, Drop, Block |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProxyAccessType
Определяет, какой механизм используется для разрешения имени узла. Допустимые значения для этого параметра:
- IEConfig
- WinHttpConfig
- AutoDetect
- NoProxyServer
- None
По умолчанию используется None.
Сведения о значениях этого параметра см. в разделе Перечисление ProxyAccessType.
Type: | ProxyAccessType |
Accepted values: | None, IEConfig, WinHttpConfig, AutoDetect, NoProxyServer |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProxyAuthentication
Задает метод аутентификации, используемый для разрешения прокси-сервера. Допустимые значения для этого параметра: Basic, Digest и Negotiate. Значение по умолчанию — Negotiate.
Дополнительные сведения о значениях этого параметра см. в разделе Перечисление AuthenticationMechanism.
Type: | AuthenticationMechanism |
Accepted values: | Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos |
Position: | Named |
Default value: | Negotiate |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProxyCredential
Задает учетные данные, используемые для аутентификации прокси-сервера. Введите переменную, содержащую объект PSCredential или команду, которая получает объект PSCredential , например Get-Credential
команду. Если этот параметр не установлен, учетные данные не заданы.
Type: | PSCredential |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SkipCACheck
Указывает, что при подключении по протоколу HTTPS клиент не проверяет, подписан ли сертификат сервера доверенным центром сертификации (ЦС).
Используйте этот параметр только в том случае, если имеются другие основания считать удаленный компьютер доверенным, например, если он входит в состав физически защищенной и изолированной сети либо указан в качестве доверенного узла в конфигурации службы удаленного управления Windows.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SkipCNCheck
Указывает, что общее имя сертификата (CN) сервера не обязательно совпадает с именем узла сервера. Этот параметр используется только для удаленных операций, использующих протокол HTTPS.
Используйте этот параметр только для доверенных компьютеров.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SkipRevocationCheck
Не проверяет состояние отзыва сертификата сервера.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UICulture
Указывает язык и региональные параметры пользовательского интерфейса, используемые для сеанса.
Допустимые значения:
- Имя языка и региональных параметров в
<languagecode2>-<country/regioncode2>
формате, напримерja-JP
- Переменная, содержащая объект CultureInfo .
- Команда, которая получает объект CultureInfo , например
Get-Culture
Значение по умолчанию — $null
, а язык и региональные параметры пользовательского интерфейса, заданные в операционной системе при создании сеанса, используются в сеансе.
Type: | CultureInfo |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UseUTF16
Указывает, что этот командлет кодирует запрос в формате UTF16, а не в формате UTF8.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Входные данные
None
В этот командлет нельзя передать входные данные.
Выходные данные
Примечания
Если параметр SessionOption не используется в команде для создания PSSession, параметры сеанса определяются значениями свойств переменной $PSSessionOption
предпочтения, если она задана. Дополнительные сведения о переменной см. в $PSSessionOption
разделе about_Preference_Variables.
Свойства объекта конфигурации сеанса зависят от заданных для конфигурации сеанса параметров и значений этих параметров. Кроме того, конфигурации сеансов, определяющие с помощью файла конфигурации, включают дополнительные свойства.