about_WorkflowCommonParameters

Artigo
10/04/2023

BREVE DESCRIÇÃO

Este tópico descreve os parâmetros que são válidos em todos os comandos de fluxo de trabalho do Windows PowerShell. Como o mecanismo do Windows PowerShell os adiciona aos fluxos de trabalho, você pode usar esses parâmetros em qualquer fluxo de trabalho e eles são habilitados automaticamente nos fluxos de trabalho criados.

DESCRIÇÃO LONGA

Os parâmetros comuns do Fluxo de Trabalho do Windows PowerShell são um conjunto de parâmetros de cmdlet que você pode usar com todos os fluxos de trabalho e atividades do Windows PowerShell. Eles são adicionados pelo mecanismo de Fluxo de Trabalho do Windows PowerShell, não pelo autor do fluxo de trabalho, e ficam automaticamente disponíveis em fluxos de trabalho e atividades. No entanto, os fluxos de trabalho aninhados com três níveis de profundidade não suportam parâmetros comuns, incluindo parâmetros comuns do fluxo de trabalho.

Todos os parâmetros do fluxo de trabalho são opcionais e nomeados (não posicionais). Eles não recebem entrada do gasoduto.

A maioria dos parâmetros comuns do fluxo de trabalho tem um PS prefixo, como PSComputerName e PSCredential. Os parâmetros prefixados PS configuram a conexão e o ambiente de execução para os computadores de destino, também conhecidos como "nós remotos".

Muitos dos parâmetros comuns do fluxo de trabalho, como PSAllowRedirection e AsJob, têm nomes semelhantes aos parâmetros usados em trabalhos remotos e em segundo plano do Windows PowerShell. Esses parâmetros funcionam da mesma forma que os parâmetros de comunicação remota e de trabalho com nomes semelhantes, para que você possa usar o conhecimento desenvolvido em comunicação remota e trabalhos para gerenciar fluxos de trabalho.

Os fluxos de trabalho são introduzidos no Windows PowerShell 3.0.

DESCRIÇÕES DOS PARÂMETROS

Esta seção descreve os parâmetros comuns do fluxo de trabalho.

-AsJob <SwitchParameter>

Executa o fluxo de trabalho como um trabalho de fluxo de trabalho. O comando workflow retorna imediatamente um objeto que representa um trabalho pai. O trabalho pai contém os trabalhos filho que estão sendo executados em cada um dos computadores de destino. Para gerenciar o trabalho, use os cmdlets Job. Para obter os resultados do trabalho, use Receive-Job.

-JobName <String>

Especifica um nome amigável para o trabalho de fluxo de trabalho. Por padrão, os trabalhos são nomeados Job<n>, onde <n> é um número ordinal.

Se você usar o parâmetro JobName em um comando de fluxo de trabalho, o fluxo de trabalho será executado como um trabalho e o comando de fluxo de trabalho retornará um objeto de trabalho, mesmo que você não inclua o parâmetro AsJob no comando.

Para obter mais informações sobre trabalhos em segundo plano do Windows PowerShell, consulte about_Jobs.

-PSAllowRedirection <SwitchParameter>

Permite o redirecionamento da conexão para os computadores de destino.

Quando você usa o parâmetro PSConnectionURI , o destino remoto pode retornar uma instrução para redirecionar para um URI diferente. Por padrão, o Windows PowerShell não redireciona conexões, mas você pode usar o parâmetro PSAllowRedirection para permitir o redirecionamento da conexão para o computador de destino.

Você também pode limitar o número de vezes que a conexão é redirecionada definindo a propriedade MaximumConnectionRedirectionCount da variável de $PSSessionOption preferência ou a propriedade MaximumConnectionRedirectionCount do valor do parâmetro PSSessionOption . O valor predefinido é 5. Para obter mais informações, consulte a descrição do parâmetro PSSessionOption e New-PSSessionOption.

-PSApplicationName <String>

Especifica o segmento de nome do aplicativo do URI de conexão usado para se conectar aos computadores de destino. Use esse parâmetro para especificar o nome do aplicativo quando não estiver usando o parâmetro ConnectionURI no comando.

O valor padrão é o valor da variável de $PSSessionApplicationName preferência no computador local. Se essa variável de preferência não estiver definida, o valor padrão será WSMAN. Esse valor é apropriado para a maioria dos usos. Para obter mais informações, consulte about_Preference_Variables.

O serviço WinRM usa o nome do aplicativo para selecionar um ouvinte para atender à solicitação de conexão. O valor desse parâmetro deve corresponder ao valor da propriedade URLPrefix de um ouvinte no computador remoto.

-PSAuthentication <AuthenticationMechanism>

Especifica o mecanismo usado para autenticar as credenciais do usuário ao se conectar aos computadores de destino.

Os valores válidos são:

Default
Basic
Credssp
Digest
Kerberos
Negotiate
NegotiateWithImplicitCredential

O valor predefinido é Default.

Para obter informações sobre os valores desse parâmetro, consulte a descrição da enumeração System.Management.Automation.Runspaces.AuthenticationMechanism no SDK do PowerShell.

Aviso

A autenticação CredSSP (Credential Security Service Provider), na qual as credenciais do usuário são passadas para um computador remoto para ser autenticado, foi projetada para comandos que exigem autenticação em mais de um recurso, como acessar um compartilhamento de rede remoto. Este mecanismo aumenta o risco de segurança da operação remota. Se o computador remoto estiver comprometido, as credenciais que são passadas para ele podem ser usadas para controlar a sessão de rede.

-PSAuthenticationLevel <AuthenticationLevel>

Especifica o nível de autenticação para as conexões com os computadores de destino. O valor predefinido é Default.

Os valores válidos são:

Nome	Descrição
`Unchanged`	O nível de autenticação é o mesmo do comando anterior.
`Default`	Autenticação do Windows.
`None`	Sem autenticação COM.
`Connect`	Autenticação COM no nível de conexão.
`Call`	Autenticação COM no nível de chamada.
`Packet`	Autenticação COM no nível do pacote.
`PacketIntegrity`	Autenticação COM de nível de integridade de pacote.
`PacketPrivacy`	Autenticação COM no nível de privacidade de pacotes.

-PSCertificateThumbprint <String>

Especifica o certificado de chave pública digital (X509) de uma conta de usuário que tem permissão para executar essa ação. Insira a impressão digital do certificado.

Os certificados são usados na autenticação baseada em certificado de cliente. Eles só podem ser mapeados para contas de usuário locais; eles não funcionam com contas de domínio.

Para obter um certificado, use os cmdlets Get-Item ou Get-ChildItem na unidade do Windows PowerShell Cert: .

-PSComputerName <String[]>

Especifica a lista de computadores que são os nós de destino do fluxo de trabalho. Comandos ou atividades em um fluxo de trabalho são executados nos computadores especificados usando esse parâmetro. A predefinição é o computador local.

Digite o nome NETBIOS, endereço IP ou nome de domínio totalmente qualificado de um ou mais computadores em uma lista separada por vírgula. Para especificar o computador local, digite o nome localhostdo computador ou um ponto (.).

Para incluir o computador local no valor do parâmetro PSComputerName , abra o Windows PowerShell com a opção Executar como administrador .

Se esse parâmetro for omitido do comando, ou se o valor for $null ou uma cadeia de caracteres vazia, o destino do fluxo de trabalho será o computador local e a comunicação remota do Windows PowerShell não será usada para executar o comando.

Para usar um endereço IP no valor do parâmetro ComputerName , o comando deve incluir o parâmetro PSCredential . Além disso, o computador deve ser configurado para transporte HTTPS ou o endereço IP do computador remoto deve ser incluído na lista WinRM TrustedHosts no computador local. Para obter instruções sobre como adicionar um nome de computador à lista TrustedHosts, consulte "Como adicionar um computador à lista de hosts confiáveis" no about_Remote_Troubleshooting.

-PSConfigurationName <String>

Especifica as configurações de sessão que são usadas para configurar sessões nos computadores de destino. Insira uma configuração de sessão nos computadores de destino (não no computador do servidor de fluxo de trabalho). O padrão é Microsoft.PowerShell.Workflow.

-PSConnectionRetryCount <UInt>

Especifica o número máximo de tentativas de conexão a cada computador de destino se a primeira tentativa de conexão falhar. Insira um número entre 1 e 4.294.967.295 (UInt.MaxValue). O valor padrão, zero (0), representa nenhuma tentativa de repetição.

-PSConnectionRetryIntervalSec <UInt>

Especifica o atraso entre as tentativas de repetição de conexão em segundos. O valor padrão é zero (0). Este parâmetro é válido somente quando o valor de PSConnectionRetryCount é pelo menos 1.

-PSConnectionURI <System.Uri>

Especifica um URI (Uniform Resource Identifier) que define o ponto de extremidade de conexão para o fluxo de trabalho no computador de destino. O URI deve ser totalmente qualificado.

O formato desta cadeia de caracteres é o seguinte:

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

O valor predefinido é http://localhost:5985/WSMAN.

Se você não especificar um PSConnectionURI, poderá usar os parâmetros PSUseSSL, PSComputerName, PSPort e PSApplicationName para especificar os valores PSConnectionURI.

Os valores válidos para o segmento Transporte do URI são HTTP e HTTPS. Se você especificar um URI de conexão com um segmento de Transporte, mas não especificar uma porta, a sessão será criada com portas padrão: 80 para HTTP e 443 para HTTPS. Para usar as portas padrão para comunicação remota do Windows PowerShell, especifique a porta 5985 para HTTP ou 5986 HTTPS.

-PSCredential PSCredential <>

Especifica uma conta de usuário que tem permissão para executar um fluxo de trabalho no computador de destino. A predefinição é o utilizador atual. Este parâmetro é válido somente quando o parâmetro PSComputerName é incluído no comando.

Digite um nome de usuário, como User01 ou Domain01\User01, ou insira uma variável que contenha um objeto PSCredential , como um que o Get-Credential cmdlet retorna. Se introduzir apenas um nome de utilizador, ser-lhe-á solicitada uma palavra-passe.

-PSElapsedTimeoutSec <UInt32>

Determina por quanto tempo o fluxo de trabalho e todos os recursos relacionados são mantidos no sistema. Quando o tempo limite expira, o fluxo de trabalho é excluído, mesmo que ainda esteja em processamento. Insira um valor entre 10 e 4.294.967.295. O valor padrão, 0 (zero), significa que não há tempo limite decorrido.

-PSParameterCollection <Hashtable[]>

Especifica diferentes valores de parâmetros comuns do fluxo de trabalho para diferentes computadores de destino.

Introduza uma lista separada por vírgulas com uma tabela hash para cada computador de destino. Em cada tabela de hash, a primeira chave é PSComputerName e seu valor é o nome do computador de destino. Caracteres curinga são permitidos no nome do computador. Relativamente às chaves restantes na tabela hash, a chave é o nome do parâmetro e o valor é o valor do parâmetro.

Por exemplo:

-PSParameterCollection @{PSComputerName="*"; PSElapsedTimeoutSec=20},
@{PSComputerName="Server02"},
@{PSComputerName="Server03"},
@{PSComputerName="Server01"; PSElapsedTimeoutSec=10}

No exemplo acima, todas as conexões terão um PSElapsedTimeoutSec padrão de 20 segundos, exceto Server01 que substitui o valor padrão especificando seu próprio tempo limite de 10 segundos.

-PSPersist <Booleano>

Adiciona pontos de verificação ao fluxo de trabalho, além de quaisquer pontos de verificação especificados no fluxo de trabalho.

Este parâmetro não pode suprimir os pontos de verificação em um fluxo de trabalho, como aqueles especificados usando o parâmetro comum de atividade PSPersist , a Checkpoint-Workflow atividade ou a $PSPersistPreference variável.

Um "ponto de verificação" ou "ponto de persistência" é um instantâneo do estado do fluxo de trabalho e dos dados que são capturados enquanto o fluxo de trabalho é executado e são salvos em um repositório de persistência no disco ou em um banco de dados SQL. O Fluxo de Trabalho do Windows PowerShell usa os dados salvos para retomar um fluxo de trabalho suspenso ou interrompido a partir do último ponto de persistência, em vez de reiniciar o fluxo de trabalho.

Valores válidos:

(Padrão) Se você omitir esse parâmetro, um ponto de verificação será adicionado ao início e ao fim do fluxo de trabalho, além de quaisquer pontos de verificação especificados no fluxo de trabalho.
$True. Adiciona um ponto de verificação ao início e ao fim do fluxo de trabalho e um ponto de verificação após cada atividade, além de quaisquer pontos de verificação especificados no fluxo de trabalho.
$False. Nenhum ponto de verificação é adicionado. Os pontos de verificação são tomados somente quando especificados no fluxo de trabalho.

-PSPort <Int32>

Especifica a porta de rede nos computadores de destino. As portas padrão são 5985 (a porta WinRM para HTTP) e 5986 (a porta WinRM para HTTPS).

Não use o parâmetro PSPort a menos que você deve. A porta definida no comando aplica-se a todos os computadores ou sessões em que o comando é executado. Uma configuração de porta alternativa pode impedir que o comando seja executado em todos os computadores. Antes de usar uma porta alternativa, você deve configurar o ouvinte do WinRM no computador remoto para ouvir nessa porta.

-PSPrivateMetadata <Hashtable>

Fornece informações personalizadas para trabalhos de fluxo de trabalho. Introduza uma tabela hash. As chaves e os valores são personalizados para cada fluxo de trabalho. Para obter informações sobre os metadados privados de um fluxo de trabalho, consulte o tópico de ajuda do fluxo de trabalho.

Esse parâmetro não é processado pelo mecanismo de fluxo de trabalho do Windows PowerShell. Em vez disso, o motor transmite a tabela hash diretamente para o fluxo de trabalho.

-PSRunningTimeoutSec <UInt32>

Especifica o tempo de execução do fluxo de trabalho em segundos, excluindo qualquer momento em que o fluxo de trabalho seja suspenso. Se a execução do fluxo de trabalho não estiver concluída quando o tempo expirar, o mecanismo de fluxo de trabalho do Windows PowerShell interromperá forçosamente a execução do fluxo de trabalho.

-PSSessionOption <PSSessionOption>

Define opções avançadas para as sessões para os computadores de destino. Insira um objeto PSSessionOption , como um que você cria usando o New-PSSessionOption cmdlet.

Os valores padrão para as opções de sessão são determinados pelo valor da variável de $PSSessionOption preferência, se ela estiver definida. Caso contrário, a sessão usa os valores especificados na configuração da sessão.

Para obter uma descrição das opções de sessão, incluindo os valores padrão, consulte New-PSSessionOption. Para obter informações sobre a variável de $PSSessionOption preferência, consulte about_Preference_Variables.

-PSUseSSL <SwitchParameter>

Usa o protocolo SSL (Secure Sockets Layer) para estabelecer uma conexão com o computador de destino. Por padrão, o SSL não é usado.

O WS-Management criptografa todo o conteúdo do Windows PowerShell transmitido pela rede. UseSSL é uma proteção adicional que envia os dados através de um HTTPS, em vez de HTTP. Se você usar esse parâmetro, mas o SSL não estiver disponível na porta usada para o comando, o comando falhará.