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
создает объект, содержащий значения по умолчанию для всех параметров. Так как каждое свойство можно изменить, можно использовать результирующий объект в качестве шаблона и создавать стандартные объекты параметров для вашего предприятия.
Можно также сохранить объект SessionOption в переменной предпочтения $PSSessionOption
. Значения этой переменной устанавливают новые значения по умолчанию для параметров сеанса. Они эффективны, если для сеанса не заданы параметры сеанса, и они имеют приоритет над параметрами, заданными в конфигурации сеанса, но их можно переопределить, указав параметры сеанса или объект SessionOption в командлете, создав сеанс. Дополнительные сведения о переменной предпочтения $PSSessionOption
см. в about_Preference_Variables.
При использовании объекта SessionOption в командлете, создающего сеанс, значения параметра сеанса имеют приоритет над значениями по умолчанию для сеансов, заданных в переменной предпочтения $PSSessionOption
и в конфигурации сеанса. Однако они не имеют приоритета над максимальными значениями, квотами или ограничениями, установленными в конфигурации сеанса. Дополнительные сведения о конфигурациях сеансов см. в about_Session_Configurations.
Примеры
Пример 1. Создание параметра сеанса по умолчанию
Эта команда создает объект SessionOption со значениями по умолчанию.
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. Настройка сеанса с помощью объекта параметра сеанса
В этом примере показано, как использовать объект SessionOption для настройки сеанса.
$pso = New-PSSessionOption -Culture "fr-fr" -MaximumReceivedObjectSize 10MB
New-PSSession -ComputerName Server01 -SessionOption $pso
Первая команда создает новый объект SessionOption и сохраняет его в значении переменной $pso
. Вторая команда использует командлет New-PSSession
для создания сеанса на удаленном компьютере Server01. Команда использует объект SessionOption в значении переменной $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. Изменение объекта параметра сеанса
В этом примере показано, что можно изменить объект SessionOption. Все свойства имеют значения чтения и записи.
$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. Создание переменной предпочтения
Эта команда создает переменную предпочтения $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
для создания объекта SessionOption со свойством SkipCNCheck. Команда сохраняет полученный объект сеанса в переменной $skipCN
.
Вторая команда использует командлет New-PSSession
для создания нового сеанса на удаленном компьютере. Переменная проверки $skipCN
используется в значении параметра SessionOption.
Так как компьютер определяется по IP-адресу, значение параметра ComputerName не соответствует ни одному из распространенных имен в сертификате, который используется для протокола SSL. В результате требуется параметр SkipCNCheck.
Сделать аргументы доступными для удаленного сеанса
В этом примере показано, как использовать параметр 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
. Дополнительные сведения о хэш-таблицах см. в about_Hash_Tables.
Затем командлет New-PSSessionOption
с помощью параметра ApplicationArguments создает объект SessionOption, сохраненный в переменной $team
. Когда New-PSSessionOption
создает объект параметров сеанса, он автоматически преобразует хэш-таблицу в значении параметра ApplicationArguments в PrimitiveDictionary, чтобы данные могли быть надежно переданы в удаленный сеанс.
Командлет New-PSSession
запускает сеанс на компьютере Server01. Он использует параметр SessionOption для включения параметров в переменную $teamOption
.
Командлет Invoke-Command
демонстрирует, что данные в переменной $team
доступны командам в удаленном сеансе. Данные отображаются в свойстве applicationArguments автоматической переменной $PSSenderInfo
.
В последнем Invoke-Command
показано, как могут использоваться данные.
Параметры
-ApplicationArguments
Указывает PrimitiveDictionary, который отправляется в удаленный сеанс. Команды и скрипты в удаленном сеансе, включая скрипты запуска в конфигурации сеанса, могут найти этот словарь в свойстве ApplicationArguments автоматической переменной $PSSenderInfo
. Этот параметр можно использовать для отправки данных в удаленный сеанс.
Дополнительные сведения см. в разделе about_Hash_Tables, about_Session_Configurationsи about_Automatic_Variables.
Тип: | PSPrimitiveDictionary |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-CancelTimeout
Определяет, сколько времени PowerShell ожидает завершения операции отмены (CTRL+C) перед её окончанием. Введите значение в миллисекундах.
Значение по умолчанию — 60000
(одна минута). Значение 0
(ноль) означает отсутствие тайм-аута; команда выполняется бесконечно.
Тип: | Int32 |
Aliases: | CancelTimeoutMSec |
Position: | Named |
Default value: | 60000 |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-Culture
Указывает язык и региональные параметры, используемые для сеанса. Введите имя культуры в формате <languagecode2>-<country/regioncode2>
(например, ja-JP
), переменную, содержащую объект CultureInfo, или команду, которая получает объект CultureInfo.
Значение по умолчанию — $Null
, а культура, заданная в операционной системе, используется в данном сеансе.
Тип: | CultureInfo |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-IdleTimeout
Определяет, сколько времени сеанс остается открытым, если удаленный компьютер не получает никакого взаимодействия с локального компьютера. Это включает сигнал сердечного ритма. По истечении интервала сеанс закрывается.
Значение времени простоя очень важно, если вы планируете отключиться и снова подключиться к сеансу. Вы можете повторно подключиться только в том случае, если сеанс не истек.
Введите значение в миллисекундах. Минимальное значение — 60000
(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 равно 240000
(4 минуты).
Тип: | Int32 |
Aliases: | IdleTimeoutMSec |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-IncludePortInSPN
Включает номер порта в имя основной службы (SPN), используемое для проверки подлинности Kerberos, например HTTP://<ComputerName>:5985
. Этот параметр позволяет клиенту, использующему имя главного узла службы, не используемое по умолчанию, проходить аутентификацию на удаленном компьютере, использующем аутентификацию Kerberos.
Этот параметр предназначен для предприятий, где несколько служб, поддерживающих проверку подлинности Kerberos, выполняются в разных учетных записях пользователей. Например, приложение IIS, допускающее аутентификацию с использованием Kerberos, может требовать, чтобы обычное имя субъекта-службы (SPN) было зарегистрировано на учетной записи пользователя, отличающейся от учетной записи компьютера. В таких случаях удаленное взаимодействие PowerShell не может использовать Kerberos для аутентификации, так как для этого требуется SPN, зарегистрированный в учетной записи компьютера. Чтобы устранить эту проблему, администраторы могут создавать различные SPN, такие как с использованием Setspn.exe
, которые зарегистрированы на разные учетные записи пользователей, и различать их, добавляя номер порта в SPN.
Дополнительные сведения см. в разделе Setspn Overview.
Этот параметр появился в Windows PowerShell 3.0.
Тип: | SwitchParameter |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-MaxConnectionRetryCount
Указывает количество попыток подключения PowerShell к целевому компьютеру, если текущая попытка завершается ошибкой из-за проблем с сетью. Значение по умолчанию — 5
.
Этот параметр был добавлен для PowerShell версии 5.0.
Тип: | Int32 |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-MaximumReceivedDataSizePerCommand
Указывает максимальное количество байтов, которое локальный компьютер может получать с удаленного компьютера в одной команде. Введите значение в байтах. По умолчанию размер данных не ограничен.
Этот параметр предназначен для защиты ресурсов на клиентском компьютере.
Тип: | Int32 |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-MaximumReceivedObjectSize
Указывает максимальный размер объекта, который локальный компьютер может получать с удаленного компьютера. Этот параметр предназначен для защиты ресурсов на клиентском компьютере. Введите значение в байтах.
В Windows PowerShell 2.0, если этот параметр не указан, ограничение размера объекта отсутствует. Начиная с Windows PowerShell 3.0, если этот параметр не указан, значение по умолчанию равно 209715200
байтам (или 200MB
).
Тип: | Int32 |
Position: | Named |
Default value: | 209715200 |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-MaximumRedirection
Определяет, сколько раз PowerShell перенаправляет подключение к альтернативному универсальному идентификатору ресурса (URI) до сбоя подключения. Значение по умолчанию — 5
. Значение 0
(ноль) предотвращает все перенаправления.
Этот параметр используется в сеансе только в том случае, если параметр AllowRedirection используется в команде, которая создает сеанс.
Тип: | Int32 |
Position: | Named |
Default value: | 5 |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-NoCompression
Отключение сжатия пакетов в сеансе. Сжатие использует больше циклов процессора, но делает передачу быстрее.
Тип: | SwitchParameter |
Position: | Named |
Default value: | False |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-NoEncryption
Отключает шифрование данных.
Тип: | SwitchParameter |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-NoMachineProfile
Запрещает загрузку профиля пользователя Windows. В результате сеанс может быть создан быстрее, но параметры реестра, относящиеся к пользователю, такие как переменные среды, и сертификаты недоступны в сеансе.
Тип: | SwitchParameter |
Position: | Named |
Default value: | False |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-OpenTimeout
Определяет, сколько времени клиентский компьютер ожидает установления сеансового соединения. Когда интервал истекает, команда на установку подключения завершается ошибкой. Введите значение в миллисекундах.
Значение по умолчанию — 180000
(3 минуты). Значение 0
(ноль) означает отсутствие времени ожидания; команда выполняется бесконечно.
Тип: | Int32 |
Aliases: | OpenTimeoutMSec |
Position: | Named |
Default value: | 180000 (3 minutes) |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-OperationTimeout
Определяет максимальное время, в течение которого WinRM ожидает положительных результатов тестов подключения от активного соединения перед тем, как инициировать процедуру истечения времени ожидания соединения. Дополнительные сведения о WinRM см. в документации Windows Remote Management.
OperationTimeoutне накладывает ограничения по времени на команды или процессы, выполняемые в удаленном сеансе, и не влияет на другие протоколы удаленного взаимодействия, такие как SSH.
Значение по умолчанию — 180000
(3 минуты). Значение 0
(ноль) означает отсутствие времени ожидания.
Тип: | Int32 |
Aliases: | OperationTimeoutMSec |
Position: | Named |
Default value: | 180000 (3 minutes) |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-OutputBufferingMode
Определяет, как результаты команды обрабатываются в сеансах с отключённым подключением, когда выходной буфер становится полным.
Если режим буферизации выходных данных не задан в сеансе или в конфигурации сеанса, значение по умолчанию Block
. Пользователи также могут изменить режим буферизации выходных данных при отключении сеанса.
Если этот параметр не указан, значение OutputBufferingMode объекта SessionOption равно None
. Значение Block
или Drop
переопределяет параметр транспорта режима буферизации вывода в конфигурации сеанса. Допустимые значения для этого параметра:
-
Block
. Когда выходной буфер заполнен, выполнение будет приостановлено до тех пор, пока буфер не будет снят. -
Drop
. Когда выходной буфер заполнен, выполнение продолжается. При сохранении новых выходных данных старые выходные данные удаляются. -
None
. Режим буферизации выходных данных не указан.
Дополнительные сведения о параметре транспорта режима буферизации выходных данных см. в New-PSTransportOption
.
Этот параметр появился в Windows PowerShell 3.0.
Тип: | OutputBufferingMode |
Допустимые значения: | None, Drop, Block |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-ProxyAccessType
Определяет, какой механизм используется для разрешения имени узла. Допустимые значения для этого параметра:
IEConfig
WinHttpConfig
AutoDetect
NoProxyServer
None
Значение по умолчанию — None
.
Сведения о значениях этого параметра см. в перечисления ProxyAccessType.
Тип: | ProxyAccessType |
Допустимые значения: | None, IEConfig, WinHttpConfig, AutoDetect, NoProxyServer |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-ProxyAuthentication
Указывает метод проверки подлинности, используемый для определения прокси-сервера. Допустимые значения для этого параметра:
Basic
Digest
Negotiate
Значение по умолчанию — Negotiate
.
Для получения дополнительной информации о значениях этого параметра см. перечисление AuthenticationMechanism.
Тип: | AuthenticationMechanism |
Допустимые значения: | Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos |
Position: | Named |
Default value: | Negotiate |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-ProxyCredential
Указывает учетные данные, используемые для проверки подлинности прокси-сервера. Введите переменную, содержащую объект PSCredential или команду, которая получает объект PSCredential, например команду Get-Credential
. Если этот параметр не задан, учетные данные не указаны.
Тип: | PSCredential |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-SkipCACheck
Указывает, что при подключении по протоколу HTTPS клиент не проверяет, подписан ли сертификат сервера доверенным центром сертификации (ЦС).
Используйте этот параметр, только если удаленный компьютер является доверенным с помощью другого механизма, например, когда удаленный компьютер является частью сети, которая физически безопасна и изолирована или когда удаленный компьютер указан в качестве доверенного узла в конфигурации WinRM.
Тип: | SwitchParameter |
Position: | Named |
Default value: | False |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-SkipCNCheck
Указывает, что общее имя сертификата (CN) сервера не обязательно совпадает с именем узла сервера. Этот параметр используется только в удаленных операциях, использующих протокол HTTPS.
Используйте этот параметр только для доверенных компьютеров.
Тип: | SwitchParameter |
Position: | Named |
Default value: | False |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-SkipRevocationCheck
Не проверяет состояние отзыва сертификата сервера.
Тип: | SwitchParameter |
Position: | Named |
Default value: | False |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-UICulture
Указывает культуру пользовательского интерфейса, используемую для сеанса.
Допустимые значения:
- Название культуры в формате
<languagecode2>-<country/regioncode2>
, напримерja-JP
- Переменная , содержащая объект CultureInfo
- Команда, которая получает объект CultureInfo, например
Get-Culture
Значение по умолчанию — $null
, а также язык и региональные параметры пользовательского интерфейса, которые установлены в операционной системе при создании сеанса.
Тип: | CultureInfo |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
-UseUTF16
Указывает, что этот командлет кодирует запрос в формате UTF16 вместо формата UTF8.
Тип: | SwitchParameter |
Position: | Named |
Default value: | None |
Обязательно: | False |
Принять входные данные конвейера: | False |
Принять подстановочные знаки: | False |
Входные данные
None
Невозможно передать объекты в этот командлет.
Выходные данные
Примечания
Если параметр sessionOption не используется в команде для создания PSSession, параметры сеанса определяются значениями свойств переменной предпочтения $PSSessionOption
, если она задана. Дополнительные сведения об переменной $PSSessionOption
см. в about_Preference_Variables.
Свойства объекта конфигурации сеанса зависят от параметров конфигурации сеанса и значений этих параметров. Кроме того, конфигурации сеансов, использующие файл конфигурации сеанса, имеют дополнительные свойства.
Связанные ссылки
PowerShell