Start-Job
Inicia um trabalho em segundo plano do PowerShell.
Sintaxe
Start-Job
[-Name <String>]
[-ScriptBlock] <ScriptBlock>
[-Credential <PSCredential>]
[-Authentication <AuthenticationMechanism>]
[[-InitializationScript] <ScriptBlock>]
[-WorkingDirectory <String>]
[-RunAs32]
[-PSVersion <Version>]
[-InputObject <PSObject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Start-Job
[-DefinitionName] <String>
[[-DefinitionPath] <String>]
[[-Type] <String>]
[-WorkingDirectory <String>]
[<CommonParameters>]
Start-Job
[-Name <String>]
[-Credential <PSCredential>]
[-FilePath] <String>
[-Authentication <AuthenticationMechanism>]
[[-InitializationScript] <ScriptBlock>]
[-WorkingDirectory <String>]
[-RunAs32]
[-PSVersion <Version>]
[-InputObject <PSObject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Start-Job
[-Name <String>]
[-Credential <PSCredential>]
-LiteralPath <String>
[-Authentication <AuthenticationMechanism>]
[[-InitializationScript] <ScriptBlock>]
[-WorkingDirectory <String>]
[-RunAs32]
[-PSVersion <Version>]
[-InputObject <PSObject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Description
O cmdlet Start-Job
inicia um trabalho em segundo plano do PowerShell no computador local.
Um trabalho em segundo plano do PowerShell executa um comando sem interagir com a sessão atual. Quando você inicia um trabalho em segundo plano, um objeto de trabalho retorna imediatamente, mesmo que o trabalho tenha um tempo estendido para ser concluído. Você pode continuar a trabalhar na sessão sem interrupção enquanto a tarefa está sendo executada.
O objeto de trabalho contém informações úteis sobre o trabalho, mas não contém os resultados do trabalho.
Quando o trabalho for concluído, use o cmdlet Receive-Job
para obter os resultados do trabalho. Para obter mais informações sobre trabalhos em segundo plano, consulte about_Jobs.
Para executar um trabalho em segundo plano em um computador remoto, use o parâmetro AsJob disponível em muitos cmdlets ou use o cmdlet Invoke-Command
para executar um comando Start-Job
no computador remoto. Para obter mais informações, consulte about_Remote_Jobs.
A partir do PowerShell 3.0, Start-Job
pode iniciar instâncias de tipos de trabalho personalizados, como trabalhos agendados. Para obter informações sobre como usar Start-Job
para iniciar trabalhos com tipos personalizados, consulte os documentos de ajuda para o recurso de tipo de trabalho.
A partir do PowerShell 6.0, você pode iniciar trabalhos usando o operador de plano de fundo ampersand (&
). A funcionalidade do operador em segundo plano é semelhante a Start-Job
. Ambos os métodos para iniciar um trabalho criam um objeto de trabalho PSRemotingJob. Para mais informações sobre o uso do ampersand (&
), consulte about_Operators.
O PowerShell 7 introduziu o parâmetro WorkingDirectory que especifica o diretório de trabalho inicial de um trabalho em segundo plano. Se o parâmetro não for especificado, Start-Job
o padrão será o diretório de trabalho atual do chamador que iniciou o trabalho.
Nota
Não há suporte para a criação de um trabalho em segundo plano fora do processo com Start-Job
no cenário em que o PowerShell está sendo hospedado em outros aplicativos, como o PowerShell Azure Functions.
Isso ocorre por design porque Start-Job
depende do pwsh
executável estar disponível em $PSHOME
para iniciar um trabalho em segundo plano fora de processo, mas quando um aplicativo está hospedando o PowerShell, ele está usando diretamente os pacotes do SDK do NuGet do PowerShell e não terá pwsh
incluído.
O substituto nesse cenário é Start-ThreadJob
do módulo ThreadJob.
Exemplos
Exemplo 1: iniciar um trabalho em segundo plano
Este exemplo inicia um trabalho em segundo plano que é executado no computador local.
Start-Job -ScriptBlock { Get-Process -Name pwsh }
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
1 Job1 BackgroundJob Running True localhost Get-Process -Name pwsh
Start-Job
usa o parâmetro ScriptBlock para executar Get-Process
como um trabalho em segundo plano. O parâmetro Name especifica para localizar processos do PowerShell, pwsh
. As informações do trabalho são exibidas e o PowerShell retorna a um prompt enquanto o trabalho é executado em segundo plano.
Para exibir a saída do trabalho, use o cmdlet Receive-Job
. Por exemplo, Receive-Job -Id 1
.
Exemplo 2: Usar o operador em segundo plano para iniciar um trabalho em segundo plano
Este exemplo usa o operador de plano de fundo ampersand (&
) para iniciar um trabalho em segundo plano no computador local. O trabalho obtém o mesmo resultado que Start-Job
no Exemplo 1.
Get-Process -Name pwsh &
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
5 Job5 BackgroundJob Running True localhost Microsoft.PowerShell.Man...
Get-Process
usa o parâmetro Name para especificar processos do PowerShell, pwsh
. O ampersand (&
) executa o comando como um trabalho em segundo plano. As informações do trabalho são exibidas e o PowerShell retorna a um prompt enquanto o trabalho é executado em segundo plano.
Para exibir a saída do trabalho, use o cmdlet Receive-Job
. Por exemplo, Receive-Job -Id 5
.
Exemplo 3: iniciar um trabalho usando Invoke-Command
Este exemplo executa um trabalho em vários computadores. O trabalho é armazenado em uma variável e é executado usando o nome da variável na linha de comando do PowerShell.
$jobWRM = Invoke-Command -ComputerName (Get-Content -Path C:\Servers.txt) -ScriptBlock {
Get-Service -Name WinRM } -JobName WinRM -ThrottleLimit 16 -AsJob
Um trabalho que usa Invoke-Command
é criado e armazenado na variável $jobWRM
.
Invoke-Command
usa o parâmetro ComputerName para especificar os computadores em que o trabalho é executado.
Get-Content
obtém os nomes do servidor do arquivo C:\Servers.txt
.
O parâmetro ScriptBlock especifica um comando que Get-Service
acessa o serviço WinRM. O parâmetro JobName especifica um nome amigável para o trabalho, WinRM. O parâmetro ThrottleLimit limita o número de comandos simultâneos para 16. O parâmetro AsJob inicia um trabalho em segundo plano que executa o comando nos servidores.
Exemplo 4: Obter informações de trabalho
Este exemplo obtém informações sobre um trabalho e exibe os resultados de um trabalho concluído que foi executado no computador local.
$j = Start-Job -ScriptBlock { Get-WinEvent -Log System } -Credential Domain01\User01
$j | Select-Object -Property *
State : Completed
HasMoreData : True
StatusMessage :
Location : localhost
Command : Get-WinEvent -Log System
JobStateInfo : Completed
Finished : System.Threading.ManualResetEvent
InstanceId : 27ce3fd9-40ed-488a-99e5-679cd91b9dd3
Id : 18
Name : Job18
ChildJobs : {Job19}
PSBeginTime : 8/8/2019 14:41:57
PSEndTime : 8/8/2019 14:42:07
PSJobTypeName : BackgroundJob
Output : {}
Error : {}
Progress : {}
Verbose : {}
Debug : {}
Warning : {}
Information : {}
Start-Job
usa o parâmetro ScriptBlock para executar um comando que especifica Get-WinEvent
para obter o log do Sistema. O parâmetro Credential especifica uma conta de usuário de domínio com permissão para executar o trabalho no computador. O objeto de trabalho é armazenado na variável $j
.
O objeto na variável $j
é enviado pelo pipeline para Select-Object
. O parâmetro Property especifica um asterisco (*
) para exibir todas as propriedades do objeto de trabalho.
Exemplo 5: executar um script como um trabalho em segundo plano
Neste exemplo, um script no computador local é executado como um trabalho em segundo plano.
Start-Job -FilePath C:\Scripts\Sample.ps1
Start-Job
usa o parâmetro FilePath para especificar um arquivo de script armazenado no computador local.
Exemplo 6: Obter um processo usando um trabalho em segundo plano
Este exemplo usa um trabalho em segundo plano para obter um processo especificado por nome.
Start-Job -Name PShellJob -ScriptBlock { Get-Process -Name PowerShell }
Start-Job
usa o parâmetro Name para especificar um nome de trabalho amigável, PShellJob. O parâmetro ScriptBlock especifica Get-Process
para obter processos com o nome PowerShell.
Exemplo 7: Coletar e salvar dados usando um trabalho em segundo plano
Este exemplo inicia um trabalho que coleta uma grande quantidade de dados de mapa e os salva em um arquivo .tif
.
Start-Job -Name GetMappingFiles -InitializationScript {Import-Module -Name MapFunctions} -ScriptBlock {
Get-Map -Name * | Set-Content -Path D:\Maps.tif }
Start-Job
usa o parâmetro Name para especificar um nome de trabalho amigável, GetMappingFiles. O parâmetro InitializationScript executa um bloco de script que importa o módulo MapFunctions. O parâmetro ScriptBlock é executado Get-Map
e Set-Content
salva os dados no local especificado pelo parâmetro Path.
Exemplo 8: Passar a entrada para um trabalho em segundo plano
Este exemplo usa a variável automática $input
para processar um objeto de entrada. Use Receive-Job
para ver o resultado do trabalho.
Start-Job -ScriptBlock { Get-Content -Path $input } -InputObject "C:\Servers.txt"
Receive-Job -Name Job45 -Keep
Server01
Server02
Server03
Server04
Start-Job
usa o parâmetro ScriptBlock para executar Get-Content
com a variável automática $input
. A variável $input
obtém objetos do parâmetro InputObject.
Receive-Job
usa o parâmetro Name para especificar o trabalho e gera os resultados. O parâmetro Keep salva o resultado do trabalho, permitindo que ele seja exibido novamente durante a sessão do PowerShell.
Exemplo 9: Definir o diretório de trabalho para um trabalho em segundo plano
O WorkingDirectory permite especificar um diretório alternativo para um trabalho do qual você pode executar scripts ou abrir arquivos. Neste exemplo, o trabalho em segundo plano especifica um diretório de trabalho diferente do local de diretório atual.
PS C:\Test> Start-Job -WorkingDirectory C:\Test\Scripts { $PWD } | Receive-Job -AutoRemoveJob -Wait
Path
----
C:\Test\Scripts
O diretório de trabalho atual deste exemplo é C:\Test
.
Start-Job
usa o parâmetro WorkingDirectory para especificar o diretório de trabalho. O parâmetro ScriptBlock usa $PWD
para mostrar o diretório de trabalho da tarefa.
Receive-Job
exibe a saída do trabalho em segundo plano.
AutoRemoveJob exclui o trabalho e Wait suprime o prompt de comando até que todos os resultados sejam recebidos.
Exemplo 10: Usar o parâmetro ArgumentList para especificar uma matriz
Este exemplo usa o parâmetro ArgumentList para especificar uma matriz de argumentos. A matriz é uma lista separada por vírgulas de nomes de processo.
Start-Job -ScriptBlock { Get-Process -Name $args } -ArgumentList powershell, pwsh, notepad
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
1 Job1 BackgroundJob Running True localhost Get-Process -Name $args
O cmdlet Start-Job
usa o parâmetro ScriptBlock para executar um comando.
Get-Process
usa o parâmetro Name para especificar a variável automática $args
. O parâmetro ArgumentList passa a matriz de nomes de processos para $args
. Os nomes de processo powershell, pwsh e bloco de notas são processos em execução no computador local.
Para exibir a saída do trabalho, use o cmdlet Receive-Job
. Por exemplo, Receive-Job -Id 1
.
Exemplo 11: Executar trabalho em um Windows PowerShell 5.1
Este exemplo usa o parâmetro PSVersion com o valor 5.1 para executar o trabalho em uma sessão do Windows PowerShell 5.1.
$PSVersionTable.PSVersion
Major Minor Patch PreReleaseLabel BuildLabel
----- ----- ----- --------------- ----------
7 0 0 rc.1
$job = Start-Job -ScriptBlock { $PSVersionTable.PSVersion } -PSVersion 5.1
Receive-Job -Job $job
Major Minor Build Revision
----- ----- ----- --------
5 1 14393 3383
Parâmetros
-ArgumentList
Especifica uma matriz de argumentos ou valores de parâmetro para o script especificado pelo parâmetro FilePath ou um comando especificado com o parâmetro ScriptBlock.
Os argumentos devem ser passados para argumentList como argumento de matriz de dimensão única. Por exemplo, uma lista separada por vírgulas. Para obter mais informações sobre o comportamento de ArgumentList, consulte about_Splatting.
Tipo: | Object[] |
Aliases: | Args |
Cargo: | Named |
Valor padrão: | None |
Obrigatório: | False |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-Authentication
Especifica o mecanismo usado para autenticar as credenciais do usuário.
Os valores aceitáveis para esse parâmetro são os seguintes:
- Padrão
- Básico
- Credssp
- Resumo
- Kerberos
- Negociar
- NegotiateWithImplicitCredential
O valor padrão é Default.
A autenticação credSSP está disponível apenas no Windows Vista, windows server 2008 e versões posteriores do sistema operacional Windows.
Para obter mais informações sobre os valores desse parâmetro, consulte AuthenticationMechanism.
Cuidado
A autenticação CredSSP (o Provedor de Suporte à Segurança de Credencial), na qual as credenciais do usuário são passadas para autenticação em um computador remoto, é 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 passadas para ele poderão ser usadas para controlar a sessão de rede.
Tipo: | AuthenticationMechanism |
Valores aceitos: | Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos |
Cargo: | Named |
Valor padrão: | Default |
Obrigatório: | False |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-Credential
Especifica uma conta de usuário que tem permissão para executar essa ação. Se o parâmetro Credential não for especificado, o comando usará as credenciais do usuário atual.
Digite um nome de usuário, como user01 ou Domain01\User01, ou insira um objeto PSCredential gerado pelo cmdlet Get-Credential
. Se você digitar um nome de usuário, será solicitado que você insira a senha.
As credenciais são armazenadas em um objeto PSCredential e a senha é armazenada como um SecureString.
Nota
Para obter mais informações sobre a proteção de dados SecureString, consulte Qual é o nível de segurança de SecureString?.
Tipo: | PSCredential |
Cargo: | Named |
Valor padrão: | Current user |
Obrigatório: | False |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-DefinitionName
Especifica o nome da definição do trabalho iniciado por esse cmdlet. Use esse parâmetro para iniciar tipos de trabalho personalizados que têm um nome de definição, como trabalhos agendados.
Quando você usa Start-Job
para iniciar uma instância de um trabalho agendado, o trabalho é iniciado imediatamente, independentemente de gatilhos de trabalhos ou opções de trabalhos. A instância de trabalho resultante é um trabalho agendado, mas ele não é salvo no disco como ocorre com trabalhos agendados disparados. Você não pode usar o parâmetro ArgumentList de Start-Job
para fornecer valores para parâmetros de scripts executados em um trabalho agendado.
Esse parâmetro foi introduzido no PowerShell 3.0.
Tipo: | String |
Cargo: | 0 |
Valor padrão: | None |
Obrigatório: | True |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-DefinitionPath
Especifica o caminho da definição para o trabalho iniciado por esse cmdlet. Insira o caminho de definição. A concatenação dos valores dos parâmetros DefinitionPath e DefinitionName é o caminho totalmente qualificado da definição do trabalho. Use esse parâmetro para iniciar tipos de trabalho personalizados que têm um caminho de definição, como trabalhos agendados.
Para trabalhos agendados, o valor do parâmetro DefinitionPath é $HOME\AppData\Local\Windows\PowerShell\ScheduledJob
.
Esse parâmetro foi introduzido no PowerShell 3.0.
Tipo: | String |
Cargo: | 1 |
Valor padrão: | None |
Obrigatório: | False |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-FilePath
Especifica um script local que Start-Job
executa como um trabalho em segundo plano. Insira o caminho e o nome do arquivo do script ou use o pipeline para enviar um caminho de script para Start-Job
. O script deve estar no computador local ou em uma pasta que o computador local possa acessar.
Quando você usa esse parâmetro, o PowerShell converte o conteúdo do arquivo de script especificado em um bloco de script e executa o bloco de script como um trabalho em segundo plano.
Tipo: | String |
Cargo: | 0 |
Valor padrão: | None |
Obrigatório: | True |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-InitializationScript
Especifica os comandos executados antes do início do trabalho. Para criar um bloco de script, coloque os comandos entre chaves ({}
).
Use esse parâmetro para preparar a sessão na qual o trabalho é executado. Por exemplo, você pode usá-lo para adicionar funções, snap-ins e módulos à sessão.
Tipo: | ScriptBlock |
Cargo: | 1 |
Valor padrão: | None |
Obrigatório: | False |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-InputObject
Especifica a entrada para o comando. Insira uma variável que contenha os objetos ou digite um comando ou expressão que gere os objetos.
No valor do parâmetro ScriptBlock, use a variável automática $input
para representar os objetos de entrada.
Tipo: | PSObject |
Cargo: | Named |
Valor padrão: | None |
Obrigatório: | False |
Aceitar a entrada de pipeline: | True |
Aceitar caracteres curinga: | False |
-LiteralPath
Especifica um script local que este cmdlet executa como um trabalho em segundo plano. Insira o caminho de um script no computador local.
Start-Job
usa o valor do parâmetro LiteralPath exatamente como ele é digitado. Nenhum caractere é interpretado como caractere curinga. Se o caminho incluir caracteres de escape, coloque-o entre aspas simples. As aspas simples dizem ao PowerShell a não interpretar nenhum caractere como sequências de escape.
Tipo: | String |
Aliases: | PSPath, LP |
Cargo: | Named |
Valor padrão: | None |
Obrigatório: | True |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-Name
Especifica um nome amigável para o novo trabalho. Você pode usar o nome para identificar o trabalho em outros cmdlets de trabalhos, como o cmdlet Stop-Job
.
O nome amigável padrão é Job#
, em que #
é um número ordinal incrementado para cada trabalho.
Tipo: | String |
Cargo: | Named |
Valor padrão: | None |
Obrigatório: | False |
Aceitar a entrada de pipeline: | True |
Aceitar caracteres curinga: | False |
-PSVersion
Especifica uma versão do PowerShell a ser usada para executar o trabalho. Quando o valor de PSVersion é 5.1 O trabalho é executado em uma sessão do Windows PowerShell 5.1. Para qualquer outro valor, o trabalho é executado usando a versão atual do PowerShell.
Esse parâmetro foi adicionado ao PowerShell 7 e só funciona no Windows.
Tipo: | Version |
Cargo: | Named |
Valor padrão: | None |
Obrigatório: | False |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-RunAs32
A partir do PowerShell 7, o parâmetro RunAs32 não funciona no PowerShell de 64 bits (pwsh
).
Se RunAs32 for especificado no PowerShell de 64 bits, Start-Job
gerará um erro de exceção de encerramento.
Para iniciar um processo do PowerShell de 32 bits (pwsh
) com RunAs32, é preciso ter o PowerShell de 32 bits instalado.
No PowerShell de 32 bits, RunAs32 força o trabalho a ser executado em um processo de 32 bits, mesmo em um sistema operacional de 64 bits.
Em versões de 64 bits do Windows 7 e do Windows Server 2008 R2, quando o comando Start-Job
inclui o parâmetro RunAs32, você não pode usar o parâmetro Credential para especificar as credenciais de outro usuário.
Tipo: | SwitchParameter |
Cargo: | Named |
Valor padrão: | False |
Obrigatório: | False |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-ScriptBlock
Especifica os comandos a serem executados no trabalho em segundo plano. Para criar um bloco de script, coloque os comandos entre chaves ({}
). Use a variável $input
automática para acessar o valor do parâmetro InputObject. Esse parâmetro é necessário.
Tipo: | ScriptBlock |
Aliases: | Command |
Cargo: | 0 |
Valor padrão: | None |
Obrigatório: | True |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-Type
Especifica o tipo personalizado para trabalhos iniciados por Start-Job
. Insira um nome de tipo de trabalho personalizado, como PSScheduledJob para trabalhos agendados ou PSWorkflowJob para trabalhos de fluxos de trabalho. Esse parâmetro não é válido para trabalhos em segundo plano padrão.
Esse parâmetro foi introduzido no PowerShell 3.0.
Tipo: | String |
Cargo: | 2 |
Valor padrão: | None |
Obrigatório: | False |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-WorkingDirectory
Especifica o diretório de trabalho inicial do trabalho em segundo plano. Se o parâmetro não for especificado, o trabalho será executado no local padrão. O local padrão é o diretório de trabalho atual do chamador que iniciou o trabalho.
Esse parâmetro foi introduzido no PowerShell 7.
Tipo: | String |
Cargo: | Named |
Valor padrão: | $HOME on Unix (macOS, Linux) and $HOME\Documents on Windows |
Obrigatório: | False |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
Entradas
Você pode redirecionar um objeto com a propriedade Name para o parâmetro Name para este cmdlet. Por exemplo, você pode encaminhar um objeto FileInfo de Get-ChildItem
.
Saídas
System.Management.Automation.PSRemotingJob
Esse cmdlet retorna um objeto PSRemotingJob que representa o trabalho iniciado.
Observações
O PowerShell inclui os seguintes aliases para Start-Job
:
- Todas as plataformas:
sajb
Para ser executado em segundo plano, Start-Job
é executado em uma sessão própria dentro da sessão atual. Quando você usa o cmdlet Invoke-Command
para executar um comando Start-Job
em uma sessão em um computador remoto, Start-Job
é executado em uma sessão na sessão remota.