about_ActivityCommonParameters

Назначение: Windows PowerShell 3.0

РАЗДЕЛ

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                       PSError
    ErrorAction                       PSPersist
    Input                             PSPort
    MergeErrorToOutput                PSProgress
    PSActionRetryCount                PSProgressMessage
    PSActionRetryIntervalSec          PSRemotingBehavior    
    PSActionRunningTimeoutSec         PSRequiredModules
    PSApplicationName                 PSSessionOption
    PSAuthentication                  PSUseSSL
    PSCertificateThumbprint           PSVerbose
    PSComputerName                    PSWarning
    PSConfigurationName               Result
    PSConnectionRetryCount            UseDefaultInput
    PSConnectionRetryIntervalSec      Verbose
    PSConnectionURI                   WarningAction
    PSCredential

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

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

-Appendoutput <Boolean>

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

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

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

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

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

-Debug <Параметр-переключатель>

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

-DisplayName <Строка>

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

-ErrorAction <Действие>

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

ДОПУСТИМЫЕ ЗНАЧЕНИЯ:

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

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

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

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

SilentlyContinue. Сообщение об ошибке не выводится, и выполнение команды продолжается.

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

-Input <Object[]>

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

-MergeErrorToOutput <Boolean>

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

-PSActionRetryCount <Int32>

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

-PSActionRetryIntervalSec <Int32>

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

-PSActionRunningTimeoutSec <Int32>

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

-PSAllowRedirection <Boolean>

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

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

Вы также можете ограничить число перенаправлений подключения, задав свойство MaximumConnectionRedirectionCount привилегированной переменной $PSSessionOption или свойство MaximumConnectionRedirectionCount параметра SSessionOption командлетов, создающих сеанс. Значение по умолчанию — 5.

-PSApplicationName <Строка>

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

По умолчанию используется значение привилегированной переменной $PSSessionApplicationName на конечном компьютере. Если привилегированная переменная не определена, значение по умолчанию — WSMAN. Это значение подходит для большинства случаев. Подробнее см. в разделе about_Preference_Variables (https://go.microsoft.com/fwlink/?LinkID=113248).

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

-PSAuthentication <Способ_аутентификации>

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

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

ВНИМАНИЕ! Проверка подлинности CredSSP, при применении которой учетные данные пользователя передаются на удаленный компьютер, предназначена для команд, требующих проверки подлинности для нескольких ресурсов, например для доступа к удаленной сетевой папке. Это повышает угрозу безопасности при работе в удаленном режиме. Если удаленный компьютер скомпрометирован, то передаваемые на него учетные данные могут быть использованы для управления сетевым сеансом.

-PSCertificateThumbprint <Строка>

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

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

Чтобы получить сертификат, используйте командлет Get-Item (https://go.microsoft.com/fwlink/?LinkID=113319) или Get-ChildItem (https://go.microsoft.com/fwlink/?LinkID=113308) на диске Windows PowerShell Cert:.

-PSComputerName <Строка[]>

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

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

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

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

Чтобы использовать IP-адрес в значении параметра ComputerName, команда должна включать параметр PSCredential. Кроме того, компьютер должен быть настроен для транспорта HTTPS или IP-адрес удаленного компьютера должен быть включен в список TrustedHosts службы WinRM на локальном компьютере. Инструкции по добавлению имени компьютера в список TrustedHosts см. в разделе «Добавление компьютера в список доверенных узлов» описания about_Remote_Troubleshooting (https://go.microsoft.com/fwlink/?LinkID=135188).

-PSConfigurationName <Строка>

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

-PSConnectionRetryCount <UInt>

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

-PSConnectionRetryIntervalSec <UInt>

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

-PSConnectionURI <System.Uri>

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

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

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

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

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

Допустимые значения для сегмента транспорта URI — HTTP и HTTPS. Если указать URI подключения с сегментом Transport, но не указать порт, сеанс будет создан со стандартными портами: 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 <Boolean>

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

-PSDisableSerializationPreference <Boolean>

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

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

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

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

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

-PSError <PSDataCollection[ErrorRecord]>

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

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

workflow Test-Workflow

            {    
                 $errorCollection = New-Object -Type System.Management.Automation.PSDataCollection[System.Management.Automation.ErrorRecord]
                 InlineScript {\\Server01\Share01\Get-AssetData.ps1} -PSError $errorCollection
                 InlineScript {\\Server01\Share01\Set-AssetData.ps1} -PSError $errorCollection
                 if ($errorCollection.Count -gt 2) { ...}
            } 

-PSPersist <Boolean>

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

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

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

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

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

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

-PSPort <Int32>

Задает сетевой порт на конечных компьютерах. Порты по умолчанию: 5985 (порт службы удаленного управления Windows для HTTP) и 5986 (порт службы удаленного управления Windows для HTTPS). Этот общий параметр действий также является общим параметром рабочего процесса.

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

-PSProgress <PSDataCollection[ProgressRecord]>

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

-PSProgressMessage <Строка>

Задает понятное описание действия. Значение 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 (https://go.microsoft.com/fwlink/?LinkID=144305).

Подробнее о привилегированной переменной $PSSessionOption см. в разделе about_Preference_Variables (https://go.microsoft.com/fwlink/?LinkID=113248).

-PSUseSSL <Boolean>

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

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

-PSVerbose <PSDataCollection[VerboseRecord]>

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

-PSWarning <PSDataCollection[WarningRecord]>

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

-RESULT

Этот параметр допустим только в рабочих процессах 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

-Verbose <Параметр-переключатель>

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

-WarningAction <Действие>

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

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

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

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

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

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

ПРИМЕЧАНИЕ. Параметр WarningAction не переопределяет значение привилегированной переменной $WarningAction при использовании в команде для запуска сценария или функции.

ПРИМЕРЫ

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

Или вы можете использовать параметры PSConnectionRetryCount и PSConnectionRetryIntervalSec для настройки повторного выполнения определенных действий.

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

        {
             $UserDomain = Get-Content -Path .\UserComputers.txt
             $Log = (Get-EventLog -LogName "Windows PowerShell" -PSComputerName $UserDomain}
             if ($Log) ...
        } 

КЛЮЧЕВЫЕ СЛОВА

about_Activity_Common_Parameters

about_Activity_Parameters

about_ActivityParameters

СМ. ТАКЖЕ

about_Workflows

about_WorkflowCommonParameters