Sobre WorkflowCommonParameters

Artigo
06/21/2023

DESCRIÇÃO BREVE

Este tópico descreve os parâmetros válidos em todos os comandos de fluxo de trabalho Windows PowerShell. Como o mecanismo de 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 que você cria.

DESCRIÇÃO LONGA

Windows PowerShell parâmetros comuns de fluxo de trabalho são um conjunto de parâmetros de cmdlet que você pode usar com todos os fluxos de trabalho e atividades Windows PowerShell. Eles são adicionados pelo mecanismo de fluxo de trabalho Windows PowerShell, não pelo autor do fluxo de trabalho, e estão 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 dão suporte a parâmetros comuns, incluindo parâmetros comuns de fluxo de trabalho.

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

A maioria dos parâmetros comuns do fluxo de trabalho tem um prefixo PS, como PSComputerName e PSCredential. Os parâmetros prefixados por 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 Windows PowerShell trabalhos de comunicação remota e em segundo plano. Esses parâmetros funcionam da mesma forma que os parâmetros de comunicação remota e trabalho de nome semelhante, para que você possa usar o conhecimento que desenvolveu 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 DE PARÂMETRO

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 de fluxo de trabalho retorna imediatamente um objeto que representa um trabalho pai. O trabalho pai contém os trabalhos filho que estão em execução 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 chamados de "Trabalho<n>", em <que 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 AsJob parâmetro 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 com os computadores de destino.

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

Você também pode limitar o número de vezes que a conexão é redirecionada definindo a MaximumConnectionRedirectionCount propriedade da variável de $PSSessionOption preferência ou a MaximumConnectionRedirectionCount propriedade do valor do PSSessionOption parameter. O valor padrão é 5. Para obter mais informações, consulte a descrição do PSSessionOption parâmetro 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 você não estiver usando o ConnectionURI parâmetro no comando .

O valor padrão é o valor da variável de $PSSessionApplicationName preferência no computador local. Se esta variável de preferência não estiver definida, o valor padrão é 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 URLPrefix propriedade 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
Resumo da mensagem
Kerberos
Negotiate
NegotiateWithImplicitCredential

O valor padrão é Default.

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

Aviso

A autenticação CredSSP (Credencial Security Service Provider), na qual as credenciais do usuário são transmitidas a um computador remoto para autenticação, foi projetada para comandos que exigem autenticação em mais de um recurso, como acessar um compartilhamento de rede remota. 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
Inalterado	O nível de autenticação é o mesmo que o comando anterior.
Default	Autenticação do Windows.
Nenhuma	Sem autenticação COM.
Connect	Autenticação COM no nível da Conexão.
Chamar	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] (xref:Microsoft.PowerShell.Management.Get-Childitem) na unidade 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, digite o nome do computador, "localhost" ou um ponto (.).

Para incluir o computador local no valor do PSComputerName parâmetro , abra 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 Windows PowerShell comunicação remota não será usada para executar o comando.

Para usar um endereço IP no valor do ComputerName parâmetro , o comando deve incluir o PSCredential parâmetro . 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, confira "Como adicionar um computador à lista de hosts confiáveis" no about_Remote_Troubleshooting.

-PSConfigurationName <String>

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 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), não 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 é https://localhost:5985/WSMAN.

Se você não especificar um PSConnectionURI, poderá usar os PSUseSSLparâmetros , PSComputerName, PSPorte PSApplicationName para especificar os PSConnectionURI valores.

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ões: 80 para HTTP e 443 para HTTPS. Para utilizar as portas padrão para comunicação remota do Windows PowerShell, especifique a porta 5985 para HTTP ou 5986 para 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 PSCredential objeto , como aquele que o Get-Credential cmdlet retorna. Se você inserir apenas um nome de usuário, uma senha será solicitada.

-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 valores de parâmetro comuns de fluxo de trabalho diferentes para computadores de destino diferentes.

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 para 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 todos os 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 PSPersist atividade, 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 capturados enquanto o fluxo de trabalho é executado e salvo em um repositório de persistência no disco ou em um banco de dados SQL. Windows PowerShell Fluxo de Trabalho 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 todos os 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 a um ponto de verificação após cada atividade, além de todos os pontos de verificação especificados no fluxo de trabalho.
$False. Nenhum ponto de verificação é adicionado. Os pontos de verificação são feitos 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 de WinRM para HTTP) e 5986 (a porta de WinRM para HTTPS).

Não use o parâmetro PSPort, a menos que seja necessário. O conjunto de portas no comando aplica-se a todos os computadores ou sessões nos quais 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 para o fluxo de trabalho.

Esse parâmetro não é processado pelo mecanismo de fluxo de trabalho 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ça 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 PSSessionOption objeto , como aquele 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 o tópico de ajuda para o New-PSSessionOption cmdlet (xref:Microsoft.PowerShell.Core.New-PSSessionOption). Para obter informações sobre a $PSSessionOption variável de 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. O UseSSL é uma proteção adicional que envia os dados em 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á.

Compartilhar via