about_WorkflowCommonParameters

Artigo
04/13/2023

DESCRIÇÃO BREVE

Este tópico descreve os parâmetros válidos em todos os comandos de fluxo de trabalho do Windows PowerShell. Como o mecanismo do Windows PowerShell os adiciona a 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 em três níveis de profundidade não oferecem suporte a nenhum parâmetro comum, 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 informações 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 maneira que os parâmetros de trabalho e comunicação remota de nome semelhante, 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ÇÃO 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 workflow 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 $PSSessionOption variável de preferência ou a propriedade MaximumConnectionRedirectionCount do valor do parâmetro PSSessionOption . O valor padrão é 5. Para obter mais informações, consulte a descrição do parâmetro PSSessionOption e New-PSSessionOption.

-PSApplicationName <Cadeia de caracteres>

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 você não estiver usando o parâmetro ConnectionURI no comando.

O valor padrão é o $PSSessionApplicationName valor da variável de preferência no computador local. Se essa variável de preferência não estiver definida, o valor padrão será WSMAN. Esse valor é adequado 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 padrão é 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 serem autenticadas, foi projetada para comandos que exigem autenticação em mais de um recurso, como acessar um compartilhamento de rede remoto. Esse mecanismo aumenta o risco de segurança da operação remota. Se o computador remoto estiver comprometido, as credenciais que são passadas a 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 padrão é 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 da Conexão.
`Call`	Autenticação COM no nível da Chamada.
`Packet`	Autenticação COM no nível do Pacote.
`PacketIntegrity`	Autenticação COM no nível da Integridade de Pacote.
`PacketPrivacy`	Autenticação COM no nível da Privacidade de Pacote.

-PSCertificateThumbprint <String>

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

Os certificados são utilizados na autenticação baseada em certificado do cliente. Eles só podem ser mapeados para contas de usuário local. 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. O padrão é o computador local.

Digite o nome NETBIOS, o endereço IP ou o nome de domínio totalmente qualificado de um ou mais computadores em uma lista separada por vírgulas. Para especificar o computador local, localhostdigite o nome do 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 o 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" em about_Remote_Troubleshooting.

-PSConfigurationName <Cadeia de caracteres>

Especifica as configurações de sessã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 com 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). Esse 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 dessa cadeia de caracteres é o seguinte:

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

O valor padrão é 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 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. O padrão é o usuário atual. Esse 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-á pedida 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 sendo processado. 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 de fluxo de trabalho para diferentes computadores de destino.

Insira uma lista separada por vírgulas de tabelas de hash com uma tabela de 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. Para as chaves restantes na tabela de 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 <Boolean>

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

Esse 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 armazenamento 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 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 utilize o parâmetro PSPort, a menos que seja necessário. 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 de WinRM no computador remoto para escutar na porta.

-PSPrivateMetadata <Hashtable>

Fornece informações personalizadas para trabalhos de fluxo de trabalho. Insira uma tabela de 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 mecanismo passa a tabela de 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 é suspenso. Se a execução do fluxo de trabalho não for concluída quando o tempo expirar, o mecanismo de fluxo de trabalho do Windows PowerShell interromperá forçadamente 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 usará 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, 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 e o SSL não estiver disponível na porta usada para o comando, o comando falhará.