Поделиться через


about_ActivityCommonParameters

КРАТКОЕ ОПИСАНИЕ

Описывает параметры, которые рабочий процесс Windows PowerShell добавляет в действия.

ПОДРОБНОЕ ОПИСАНИЕ

Рабочий процесс Windows PowerShell добавляет общие параметры действия в действия, производные от базового класса PSActivity . Эта категория включает действия InlineScript и командлеты Windows PowerShell, реализованные как действия, такие как Get-Process и Get-WinEvent.

Общие параметры действия недопустимы для Suspend-Workflow действий и Checkpoint-Workflow они не добавляются в командлеты или выражения, которые рабочий процесс Windows PowerShell автоматически выполняется в блоке скрипта InlineScript или аналогичном действии. Общие параметры действий доступны в действии InlineScript , но не в командах в блоке сценария InlineScript .

Некоторые из распространенных параметров действия также являются общими параметрами рабочего процесса или общими параметрами Windows PowerShell. Другие распространенные параметры действия уникальны для действий.

Сведения о общих параметрах рабочего процесса см. в about_WorkflowCommonParameters. Сведения о общих параметрах Windows PowerShell см. в about_CommonParameters.

СПИСОК РАСПРОСТРАНЕННЫХ ПАРАМЕТРОВ ДЕЙСТВИЙ

AppendOutput                      PSDebug
Debug                             PSDisableSerialization
DisplayName                       PSDisableSerializationPreference
ErrorAction                       PSError
Input                             PSPersist
MergeErrorToOutput                PSPort
PSActionRetryCount                PSProgress
PSActionRetryIntervalSec          PSProgressMessage
PSActionRunningTimeoutSec         PSRemotingBehavior
PSApplicationName                 PSRequiredModules
PSAuthentication                  PSSessionOption
PSCertificateThumbprint           PSUseSSL
PSComputerName                    PSVerbose
PSConfigurationName               PSWarning
PSConnectionRetryCount            Result
PSConnectionRetryIntervalSec      UseDefaultInput
PSConnectionURI                   Verbose
PSCredential                      WarningAction

ОПИСАНИЯ ПАРАМЕТРОВ

В этом разделе описаны общие параметры действия.

Логическое значение AppendOutput <>

Значение $True добавляет выходные данные действия в значение переменной. Значение $False не влияет. По умолчанию присвоение переменной значения заменяет значение переменной.

Например, следующие команды добавляют объект процесса в объект службы в переменной $x .

Workflow Test-Workflow
{
    $x = Get-Service
    $x = Get-Process -AppendOutput $true
}

Этот параметр предназначен для рабочих процессов на основе XAML. В рабочих процессах скриптов можно также использовать += оператор назначения для добавления выходных данных в значение переменной, как показано в следующем примере.

Workflow Test-Workflow
{
    $x = Get-Service
    $x += Get-Process
}

Отладка <SwitchParameter>

Отображает сведения о операции, выполняемой командой на уровне программиста. Параметр debug переопределяет значение переменной $DebugPreference для текущей команды. Этот параметр работает только в том случае, если команда создает сообщения отладки. Этот параметр также является общим параметром Windows PowerShell.

Строка DisplayName <>

Указывает понятное имя действия. Значение DisplayName отображается на панели выполнения во время выполнения рабочего процесса и в значении свойства Progress задания рабочего процесса. Если параметр PSProgressMessage также включен в команду, содержимое индикатора выполнения отображается в <DisplayName>:<PSProgressMessage> формате.

ErrorAction <ActionPreference>

Определяет, как действие реагирует на неисключаемую ошибку из команды. Это не влияет на ошибки завершения. Этот параметр работает только в том случае, если команда создает неисключаемую ошибку, например из командлета Write-Error . Параметр ErrorAction переопределяет значение переменной $ErrorActionPreference для текущей команды. Этот параметр также является общим параметром Windows PowerShell.

Допустимые значения:

  • Continue. Отображает сообщение об ошибке и продолжает выполнять команду. По умолчанию устанавливается значение Continue.

  • Ignore. Подавляет сообщение об ошибке и продолжает выполнять команду. В отличие от SilentlyContinueэтого, Ignore не добавляет сообщение об ошибке в автоматическую $Error переменную. Это Ignore значение представлено в Windows PowerShell 3.0.

  • Inquire. Отображает сообщение об ошибке и запрашивает подтверждение перед продолжением выполнения. Это значение редко используется.

  • Suspend. Автоматически приостанавливает задание рабочего процесса, чтобы разрешить дальнейшее исследование. После изучения рабочий процесс можно возобновить.

  • SilentlyContinue. Подавляет сообщение об ошибке и продолжает выполнять команду.

  • Stop. Отображает сообщение об ошибке и останавливает выполнение команды.

Входной <объект[]>

Отправляет коллекцию объектов в действие. Этот режим является альтернативой конвейерной передаче объектов по одному за раз.

Boolean MergeErrorToOutput <Boolean>

Значение $True добавления ошибок в выходной поток. Значение $False не влияет. Используйте этот параметр с параллельными и ключевое слово для сбора ошибок и ForEach -Parallel выходных данных из нескольких параллельных команд в одной коллекции.

PSActionRetryCount <Int32>

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

PSActionRetryIntervalSec <Int32>

Определяет интервал между повторными попытками действия в секундах. Значение 0по умолчанию повторяет действие немедленно. Этот параметр действителен, только если параметр PSActionRetryCount также используется в команде.

PSActionRunningTimeoutSec <Int32>

Определяет, как долго действие может выполняться на каждом целевом компьютере. Если действие не завершится до истечения срока ожидания, рабочий процесс Windows PowerShell создает завершающееся сообщение об ошибке и останавливает обработку рабочего процесса на затронутом целевом компьютере.

Логическое значение PSAllowRedirection <>

Значение $True позволяет перенаправлять подключение к целевым компьютерам. Значение $False не влияет. Этот общий параметр действия также является общим параметром рабочего процесса.

При использовании параметра PS Подключение ionURI удаленный целевой объект может вернуть инструкцию для перенаправления в другой универсальный код ресурса (URI). По умолчанию Windows PowerShell не перенаправляет подключения, но можно использовать параметр PSAllowRedirection со значением $True , чтобы разрешить перенаправление подключения к целевому компьютеру.

Можно также ограничить количество перенаправлений подключения, задав свойство Maximum Подключение ionRedirectionCount переменной $PSSessionOption предпочтения или свойство Maximum Подключение ionRedirectionCount значения параметра SessionOption командлетов, создающих сеанс. Значение по умолчанию — 5.

Строка PSApplicationName <>

Указывает сегмент имени приложения URI подключения, который используется для подключения к целевым компьютерам. Этот параметр позволяет указать имя приложения, если в команде не используется параметр ConnectionURI. Этот общий параметр действия также является общим параметром рабочего процесса.

Значение по умолчанию — это значение переменной $PSSessionApplicationName предпочтения на целевом компьютере. Если привилегированная переменная не определена, значение по умолчанию — WSMAN. Это значение подходит для большинства случаев Дополнительные сведения см. в about_Preference_Variables.

Служба удаленного управления Windows (WinRM) использует имя приложения для выбора прослушивателя для обслуживания запроса на подключение. Значение этого параметра должно совпадать со значением свойства URLPrefix прослушивателя на удаленном компьютере.

PsAuthentication <AuthenticationMechanism>

Указывает механизм, используемый для проверки подлинности учетных данных пользователя при подключении к целевым компьютерам. Допустимые значения: Default, Basic, CredSSP, Digest, Kerberos, Negotiate и NegotiateWithImplicitCredential. Значение по умолчанию — Default. Этот общий параметр действия также является общим параметром рабочего процесса.

Сведения о значениях этого параметра см. в описании перечисления System.Management.Automation.Runspaces.AuthenticationMechanism в пакете SDK PowerShell.

Предупреждение

Проверка подлинности поставщика служб безопасности учетных данных (CredSSP), при которой учетные данные пользователя передаются на удаленный компьютер для проверки подлинности, предназначены для команд, требующих проверки подлинности на нескольких ресурсах, таких как доступ к удаленному сетевому ресурсу. Этот механизм повышает риск безопасности удаленной операции. Если удаленный компьютер скомпрометирован, учетные данные, передаваемые ему, могут использоваться для управления сетевым сеансом.

Строка PSCertificateThumbprint <>

Задает цифровой сертификат с открытым ключом (X509) учетной записи пользователя, который располагает разрешением для выполнения этого действия. Введите отпечаток сертификата. Этот общий параметр действия также является общим параметром рабочего процесса.

Сертификаты используются при проверке подлинности на основе сертификата клиента. Они могут быть сопоставлены только с локальными учетными записями пользователей; они не работают с учетными записями домена.

Чтобы получить сертификат, используйте командлеты Get-Item или Get-ChildItem на диске Windows PowerShell Cert: .

Строка PSComputerName <[]>

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

Введите имя NETBIOS, IP-адрес или полное доменное имя одного или нескольких компьютеров в списке с разделителями-запятыми. Чтобы указать локальный компьютер, введите имя localhostкомпьютера или точку (.).

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

Если этот параметр опущен из команды, или это значение $null или пустая строка, целевой рабочий процесс — локальный компьютер, а удаленное взаимодействие Windows PowerShell не используется для выполнения команды.

Чтобы использовать IP-адрес в значении параметра ComputerName , команда должна включать параметр PSCredential . Кроме того, компьютер должен быть настроен для транспорта HTTPS или IP-адрес удаленного компьютера должен быть включен в список TrustedHosts службы WinRM на локальном компьютере. Инструкции по добавлению имени компьютера в список TrustedHosts см. в разделе "Добавление компьютера в список доверенных узлов" в about_Remote_Troubleshooting.

Строка PSConfigurationName <>

Указывает конфигурации сеансов, используемые для создания сеансов на целевых компьютерах. Введите имя конфигурации сеанса на целевых компьютерах (не на компьютере, на котором выполняется рабочий процесс). Значение по умолчанию — Microsoft.PowerShell.Workflow. Этот общий параметр действия также является общим параметром рабочего процесса.

PS Подключение ionRetryCount <UInt>

Указывает максимальное количество попыток подключения к каждому целевому компьютеру, если первая попытка подключения завершается ошибкой. Введите число от 1 до 4 294 967 295 (UInt.MaxValue). Значение по умолчанию, ноль (0), не представляет попыток повторных попыток. Этот общий параметр действия также является общим параметром рабочего процесса.

PS Подключение ionRetryIntervalSec <UInt>

Указывает задержку между повторными попытками подключения в секундах. Значение по умолчанию равно нулю (0). Этот параметр действителен, только если значение PS Подключение ionRetryCount не менее 1. Этот общий параметр действия также является общим параметром рабочего процесса.

PS Подключение ionURI System.Uri <>

Указывает универсальный идентификатор ресурса (URI), определяющий конечную точку подключения для действия на целевом компьютере. Значение URI должно быть указано полностью. Этот общий параметр действия также является общим параметром рабочего процесса.

Строка имеет следующий формат:

<Transport>://<ComputerName>:<Port>/<ApplicationName>

Значение по умолчанию — http://localhost:5985/WSMAN.

Если вы не указываете PS Подключение ionURI, можно использовать параметры PSUseSSL, PSComputerName, PSPort и PSApplicationName, чтобы указать значения PS Подключение ionURI.

Допустимые значения для сегмента транспорта универсального кода ресурса (URI) и HTTPHTTPS. Если указать универсальный код ресурса (URI) подключения с сегментом транспорта, но не указать порт, сеанс создается с помощью портов стандартов: 80 для HTTP и 443 HTTPS. Чтобы использовать порты по умолчанию для удаленного взаимодействия Windows PowerShell, укажите порт 5985 для HTTP или 5986 HTTPS.

PSCredential PSCredential <>

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

Введите имя пользователя, например User01 или Domain01\User01введите переменную, содержащую объект PSCredential , например возвращаемый Get-Credential командлетом. Если ввести только имя пользователя, вам будет предложено ввести пароль.

PSDebug <PSDataCollection[DebugRecord]>

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

Чтобы использовать этот общий параметр действия, используйте New-Object командлет для создания объекта PSDataCollection с типом DebugRecord и сохранения объекта в переменной. Затем используйте переменную в качестве значения параметра PSDebug одного или нескольких действий, как показано в следующем примере.

Workflow Test-Workflow
{
    $debugCollection = New-Object -Type `
    System.Management.Automation.PSDataCollection[System.Management.Automation.DebugRecord]
    InlineScript {\Server01\Share01\Get-AssetData.ps1} -PSDebug $debugCollection -Debug $True
    InlineScript {\Server01\Share01\Set-AssetData.ps1} -PSDebug $debugCollection -Debug $True
    if ($debugCollection -like "Missing") { ...}
}

Логическое значение PSDisableSerialization <>

Направляет действие для возврата объектов live (не сериализованных) в рабочий процесс. Полученные объекты имеют методы, а также свойства, но их нельзя сохранять, когда установлена контрольная точка.

PSDisableSerializationPreference <Boolean>

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

Допустимые значения:

  • (по умолчанию) Если опущено, и вы также не добавили параметр PSDisableSerialization в действие, объекты сериализуются.

  • $True. Направляет все действия в рабочем процессе для возврата "живых" (не сериализованных) объектов. Полученные объекты имеют методы, а также свойства, но их нельзя сохранять, когда установлена контрольная точка.

  • $False. Объекты рабочего процесса сериализуются.

PSError <PSDataCollection[ErrorRecord]>

Добавляет сообщения об ошибках из действия в указанную коллекцию записей ошибок вместо записи сообщений об ошибках в консоль или в значение свойства Error задания рабочего процесса. Сообщения об ошибках из нескольких действий можно добавить в один объект коллекции записей ошибок.

Чтобы использовать этот общий параметр действия, используйте New-Object командлет для создания объекта PSDataCollection с типом ErrorRecord и сохранения объекта в переменной. Затем используйте переменную в качестве значения параметра PSError одного или нескольких действий, как показано в следующем примере.

Workflow Test-Workflow
{
   $typeName = "System.Management.Automation.PSDataCollection"
   $typeName += '[System.Management.Automation.ErrorRecord]'
   $ec = New-Object $typeName
   InlineScript {\Server01\Share01\Get-AssetData.ps1} -PSError $ec
   InlineScript {\Server01\Share01\Set-AssetData.ps1} -PSError $ec
   if ($ec.Count -gt 2)
   {
      # Do Some Work.
   }
}

PSPersist <Boolean>

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

Точка сохранения или проверка точка сохранения — это моментальный снимок состояния рабочего процесса и данных, которые записываются во время выполнения рабочего процесса и сохраняются в хранилище сохраняемости на диске. Рабочий процесс Windows PowerShell использует сохраненные данные для возобновления приостановленного или прерванного рабочего процесса с последней точки сохраняемости, а не для перезапуска рабочего процесса.

Допустимые значения:

  • (по умолчанию) Если этот параметр не указан, проверка points не добавляются. Контрольные точки принимаются на основе параметров рабочего процесса.

  • $True. Контрольная точка устанавливается после завершения действия. Эта точка проверка в дополнение к любым проверка точкам, указанным в рабочем процессе.

  • $False. Никакие проверка точки не добавляются. Контрольные точки принимаются только при указании в рабочем процессе.

PSPort <Int32>

Указывает сетевой порт на целевых компьютерах. По умолчанию используются 5985 порты (порт WinRM для HTTP) и 59'86 (порт WinRM для HTTPS). Этот общий параметр действия также является общим параметром рабочего процесса.

Не используйте параметр PSPort , если не требуется. Набор портов в команде применяется ко всем компьютерам или сеансам, на которых выполняется команда. Альтернативный порт может помешать выполнению команды на всех компьютерах. Прежде чем использовать альтернативный порт, необходимо настроить прослушиватель WinRM на удаленном компьютере для прослушивания по этому порту.

PSProgress <PSDataCollection[ProgressRecord]>

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

Строка PSProgresssMessage <>

Указывает понятное описание действия. Значение PSProgressMessage отображается на панели выполнения во время выполнения рабочего процесса. Если displayName также включен в команду, содержимое индикатора выполнения отображается в <DisplayName>:<PSProgressMessage> формате.

Этот параметр особенно полезен для идентификации действий в блоке скрипта ForEach -Parallel . Без этого сообщения действия во всех параллельных ветвях идентифицируются одному имени.

PSRemotingBehavior RemotingBehavior <>

Указывает, как удаленное взаимодействие управляется при выполнении действия на целевых компьютерах. PowerShell — это значение по умолчанию.

Допустимые значения:

  • None: действие не выполняется на удаленных компьютерах.

  • PowerShell: удаленное взаимодействие Windows PowerShell используется для выполнения действия на целевых компьютерах.

  • Custom: действие поддерживает собственный тип удаленного взаимодействия. Это значение допустимо, если командлет, реализованный в качестве действия, задает значение атрибута RemotingCapability для SupportedByCommand, а команда включает параметр ComputerName.

Строка PSRequiredModules <[]>

Импортирует указанные модули перед выполнением команды. Введите имена модулей. Модули должны быть установлены на целевом компьютере.

Модули, установленные в пути, указанном в переменной среды PSModulePath , автоматически импортируются при первом использовании любой команды в модуле. Используйте этот параметр для импорта модулей, которые не находятся в расположении PSModulePath .

Так как каждое действие в рабочем процессе выполняется в собственном сеансе, Import-Module команда импортирует модуль только в сеанс, в котором он выполняется. Она не импортирует модуль в сеансы, в которых выполняются другие действия.

PSSessionOption <PSSessionOption>

Задает дополнительные параметры сеансов на целевых компьютерах. Введите объект PSSessionOption, например объект, создаваемый с помощью командлетаNew-PSSessionOption. Этот общий параметр действия также является общим параметром рабочего процесса.

Значения по умолчанию для параметров сеанса определяются значением переменной $PSSessionOption предпочтения, если она задана. В противном случае сеанс использует значения, указанные в конфигурации сеанса.

Описание параметров сеанса, включая значения по умолчанию, см. в разделе справки для командлета New-PSSessionOption New-PSSessionOption.

Дополнительные сведения о переменной $PSSessionOption предпочтения см. в about_Preference_Variables.

Логическое значение PSUseSSL <>

Значение $True протокола SSL использует протокол SSL для установления подключения к целевому компьютеру. По умолчанию SSL не используется. Значение $False не влияет. Этот общий параметр действия также является общим параметром рабочего процесса.

Протокол WS-Management шифрует все содержимое Windows PowerShell, передаваемое по сети. UseSSL — это дополнительная защита, которая отправляет данные по протоколу HTTPS вместо HTTPS. Если вы используете этот параметр, но SSL недоступен для порт, указанному в команде, она завершается ошибкой.

PSVerbose PSDataCollection[VerboseRecord <]>

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

PSWarning <PSDataCollection[WarningRecord]>

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

Результат

Этот параметр действителен только в рабочих процессах XAML.

UseDefaultInput <Boolean>

Принимает все входные данные рабочего процесса в качестве входных данных для действия по значению.

Например, Get-Process действие в следующем примере рабочего процесса использует общий параметр действия UseDefaultInput для получения входных данных, передаваемых в рабочий процесс. При запуске рабочего процесса с входными данными эти входные данные используются действием.

workflow Test-Workflow
{
    Get-Service -UseDefaultInput $True
}

PS C:> Test-Workflow -InputObject WinRm
Status   Name        DisplayName                            PSComputerName
------   ----        -----------                            --------------
Running  winrm       Windows Remote Management (WS-Manag... localhost

Подробный <параметр SwitchParameter>

Отображает подробные сведения об операции, выполняемой командой. Эта информация напоминает сведения в трассировке или в журнале транзакций. Подробный параметр переопределяет значение переменной $VerbosePreference для текущей команды. Этот параметр работает только в том случае, если команда создает подробное сообщение. Этот параметр также является общим параметром Windows PowerShell.

WarningAction <ActionPreference>

Определяет, как действие реагирует на предупреждение. По умолчанию устанавливается значение Continue. Параметр WarningAction переопределяет значение переменной $WarningPreference для текущей команды. Этот параметр работает только в том случае, если команда создает предупреждение. Этот параметр также является общим параметром Windows PowerShell.

Допустимые значения:

  • SilentlyContinue. Подавляет предупреждающее сообщение и продолжает выполнять команду.

  • Continue. Отображает предупреждение и продолжает выполнять команду. По умолчанию устанавливается значение Continue.

  • Inquire. Отображает предупреждение и запрашивает подтверждение перед продолжением выполнения. Это значение редко используется.

  • Stop. Отображает предупреждение и останавливает выполнение команды.

Примечание.

Параметр WarningAction не переопределяет значение переменной $WarningAction предпочтения, если параметр используется в команде для запуска скрипта или функции.

Примеры

Общие параметры действий крайне удобны. Например, можно использовать параметр PSComputerName для выполнения определенных действий только в подмножестве целевых компьютеров.

Кроме того, можно использовать параметры PS Подключение ionRetryCount и PS Подключение ionRetryIntervalSec для настройки значений повторных попыток для определенных действий.

В следующем примере показано, как использовать действие PSComputerName , общие параметры для выполнения Get-EventLog действия только на компьютерах, на которые он является определенным доменом.

Workflow Test-Workflow
{
    $UserDomain = Get-Content -Path '.\UserComputers.txt'
    $Log = (Get-EventLog -LogName "Windows PowerShell" `
      -PSComputerName $UserDomain)

    if ($Log)
    {
        # Do Work Here.
    }
}

См. также