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 .

Пример 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 . Дополнительные сведения о хэш-таблицах см. здесь.

New-PSSessionOption Затем командлет с помощью параметра ApplicationArguments создает объект SessionOption, сохраненный в переменной$team. При New-PSSessionOption создании объекта параметра сеанса он автоматически преобразует хэш-таблицу в значение параметра ApplicationArguments в ПримитивDictionary, чтобы данные могли быть надежно переданы в удаленный сеанс.

Командлет 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), прежде чем завершить ее. Введите значение в миллисекундах.

Значение по умолчанию — 60000 (одна минута). Значение 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

Определяет, сколько времени сеанс остается открытым, если удаленный компьютер не получает никакого взаимодействия с локального компьютера. Это включает сигнал пульса. По истечении этого времени сеанс закрывается.

Значение времени ожидания простоя имеет важное значение, если планируется отключить и повторно подключиться к сеансу. Повторно подключиться можно только в том случае, если не истекло время ожидания сеанса.

Введите значение в миллисекундах. Минимальное значение равно 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 минуты).

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, которые зарегистрированы в разных учетных записях пользователей и могут различать их, включив номер порта в имя участника-службы.

Дополнительные сведения см. в разделе "Общие сведения о Setpn".

Этот параметр впервые появился в 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, если этот параметр не указан, значение по умолчанию — 209715200 байт (или 200MB).

Type:Int32
Position:Named
Default value:209715200
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

Определяет время ожидания клиентского компьютера при установлении соединения сеанса. По истечении периода команда для установления соединения завершается с ошибкой. Введите значение в миллисекундах.

Значение по умолчанию — 180000 3 минуты. Значение 0 (ноль) означает отсутствие времени ожидания; команда продолжается бесконечно.

Type:Int32
Aliases:OpenTimeoutMSec
Position:Named
Default value:180000 (3 minutes)
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OperationTimeout

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

OperationTimeoutне накладывает ограничение времени на команды или процессы, выполняемые в удаленном сеансе, и не влияет на другие протоколы удаленного взаимодействия, такие как SSH.

Значение по умолчанию — 180000 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объекта SessionOption равно None. Значение Block или Drop переопределяет параметр транспорта режима буферизации выходных данных, заданный в конфигурации сеанса. Допустимые значения для этого параметра:

  • Block. при заполнении выходного буфера выполнение команды приостанавливается до тех пор, пока буфер не будет очищен.
  • Drop. при заполнении выходного буфера выполнение команды продолжается. Новые выходные данные сохраняются вместо наиболее старых.
  • None. порядок действий в случае переполнения выходного буфера не установлен.

Дополнительные сведения о параметре транспорта режима буферизации выходных данных см. в разделе 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

Невозможно передать объекты в этот командлет.

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

PSSessionOption

Примечания

Если параметр SessionOption не используется в команде для создания PSSession, параметры сеанса определяются значениями свойств переменной $PSSessionOption предпочтения, если он задан. Дополнительные сведения об переменной $PSSessionOption см. в about_Preference_Variables.

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