Como usar variáveis de sequência de tarefas no Configuration Manager

Aplica-se a: Configuration Manager (branch atual)

O mecanismo de sequência de tarefas no recurso de implantação do sistema operacional do Configuration Manager usa muitas variáveis para controlar seus comportamentos. Use essas variáveis para:

  • Definir condições nas etapas
  • Alterar comportamentos para etapas específicas
  • Uso em scripts para ações mais complexas

Para obter uma referência de todas as variáveis de sequência de tarefas disponíveis, consulte Variáveis de sequência de tarefas.

Tipos de variáveis

Existem vários tipos de variáveis:

Variáveis internas

As variáveis internas fornecem informações sobre o ambiente em que a sequência de tarefas é executada. Seus valores estão disponíveis em toda a sequência de tarefas. Normalmente, o mecanismo de sequência de tarefas inicializa variáveis internas antes de executar qualquer etapa.

Por exemplo, _SMSTSLogPath é uma variável de ambiente que especifica o caminho no qual os componentes do Configuration Manager gravam arquivos de log. Qualquer etapa de sequência de tarefas pode acessar essa variável de ambiente.

A sequência de tarefas avalia algumas variáveis antes de cada etapa. Por exemplo, _SMSTSCurrentActionName lista o nome da etapa atual.

Variáveis de ação

As variáveis de ação de sequência de tarefas especificam definições de configuração usadas por uma única etapa de sequência de tarefa. Por padrão, a etapa inicializa suas configurações antes de ser executada. Essas configurações estão disponíveis apenas durante a execução da etapa de sequência de tarefas associada. A sequência de tarefas adiciona o valor da variável de ação ao ambiente antes de executar a etapa. Em seguida, ele remove o valor do ambiente após a execução da etapa.

Por exemplo, você adiciona a etapa Executar Linha de Comando a uma sequência de tarefas. Esta etapa inclui uma propriedade Start In . A sequência de tarefas armazena um valor padrão para essa propriedade como a WorkingDirectory variável. A sequência de tarefas inicializa esse valor antes de executar a etapa Executar Linha de Comando . Enquanto esta etapa estiver em execução, acesse o valor da propriedade Start In do WorkingDirectory valor. Após a conclusão da etapa, a sequência de tarefas remove o valor da WorkingDirectory variável do ambiente. Se a sequência de tarefas incluir outra etapa Executar Linha de Comando , ela inicializará uma nova WorkingDirectory variável. Nesse momento, a sequência de tarefas define a variável como o valor inicial para a etapa atual. Para obter mais informações, consulte WorkingDirectory.

O valor padrão de uma variável de ação está presente quando a etapa é executada. Se você definir um novo valor, ele estará disponível para várias etapas na sequência de tarefas. Se você substituir um valor padrão, o novo valor permanecerá no ambiente. Esse novo valor substitui o valor padrão para outras etapas na sequência de tarefas. Por exemplo, você adiciona uma etapa Definir variável de sequência de tarefas como a primeira etapa da sequência de tarefas. Esta etapa define a WorkingDirectory variável como C:\. Qualquer etapa Executar Linha de Comando na sequência de tarefas usa o novo valor do diretório inicial.

Algumas etapas de sequência de tarefas marcam determinadas variáveis de ação como saída. Etapas mais adiante na sequência de tarefas, leia essas variáveis de saída.

Observação

Nem todas as etapas de sequência de tarefas têm variáveis de ação. Por exemplo, embora existam variáveis associadas à ação Ativar BitLocker , não há variáveis associadas à ação Desabilitar BitLocker .

Variáveis personalizadas

Essas variáveis são qualquer uma que o Configuration Manager não cria. Inicialize suas próprias variáveis para usar como condições, em linhas de comando ou em scripts.

Ao especificar um nome para uma nova variável de sequência de tarefas, siga estas diretrizes:

  • O nome da variável da sequência de tarefas pode incluir letras, números, o caractere de sublinhado (_) e um hífen (-).

  • Os nomes de variáveis de sequência de tarefas têm comprimento mínimo de um caractere e máximo de 256 caracteres.

  • As variáveis definidas pelo usuário devem começar com uma letra (A-Z ou a-z).

  • Nomes de variáveis definidos pelo usuário não podem começar com o caractere de sublinhado. Somente as variáveis de sequência de tarefas somente leitura são precedidas pelo caractere sublinhado.

  • Os nomes de variáveis de sequência de tarefas não diferenciam maiúsculas de minúsculas. Por exemplo, OSDVAR e osdvar são a mesma variável de sequência de tarefas.

  • Os nomes de variáveis da sequência de tarefas não podem começar nem terminar com um espaço. Eles também não podem ter espaços incorporados. A sequência de tarefas ignora quaisquer espaços no início ou no final de um nome de variável.

Não há um limite definido para quantas variáveis de sequência de tarefas você pode criar. No entanto, o número de variáveis é limitado pelo tamanho do ambiente da sequência de tarefas. O limite de tamanho total do ambiente de sequência de tarefas é de 8 KB. Para obter mais informações, consulte Reduzir o tamanho da política de sequência de tarefas.

Variáveis somente leitura

Não é possível alterar o valor de algumas variáveis, que são somente leitura. Normalmente, o nome começa com um caractere de sublinhado (_). A sequência de tarefas os usa para suas operações. Variáveis somente leitura são visíveis no ambiente de sequência de tarefas.

Essas variáveis são úteis em scripts ou linhas de comando. Por exemplo, executar uma linha de comando e canalizar a saída para um arquivo de _SMSTSLogPath log com os outros arquivos de log.

Observação

Variáveis de sequência de tarefas somente leitura podem ser lidas por etapas em uma sequência de tarefas, mas não podem ser definidas. Por exemplo, use uma variável somente leitura como parte da linha de comando para uma etapa Executar Linha de Comando . Você não pode definir uma variável somente leitura usando a etapa Definir Variável de Sequência de Tarefas .

Variáveis de matriz

A sequência de tarefas armazena algumas variáveis como uma matriz. Cada elemento na matriz representa as configurações de um único objeto. Use essas variáveis quando um dispositivo tiver mais de um objeto para configurar. As seguintes etapas de sequência de tarefas usam variáveis de matriz:

Como definir variáveis

Para variáveis personalizadas ou variáveis que não são somente leitura, há vários métodos para inicializar e definir o valor da variável:

Exclua uma variável do ambiente usando os mesmos métodos que a criação de uma variável. Para excluir uma variável, defina o valor da variável como uma cadeia de caracteres vazia.

Você pode combinar métodos para definir uma variável de sequência de tarefas com valores diferentes para a mesma sequência. Por exemplo, defina os valores padrão usando o editor de sequência de tarefas e defina valores personalizados usando um script.

Se você definir a mesma variável por métodos diferentes, o mecanismo de sequência de tarefas usará a seguinte ordem:

  1. Ele avalia primeiro as variáveis da coleção.

  2. Variáveis específicas do dispositivo substituem a mesma variável definida em uma coleção.

  3. As variáveis definidas por qualquer método durante a sequência de tarefas têm precedência sobre as variáveis de dispositivo ou coleção.

Limitações gerais para valores de variáveis de sequência de tarefas

  • Os valores das variáveis da sequência de tarefas não podem ter mais de 4.000 caracteres.

  • Não é possível alterar uma variável de sequência de tarefas somente leitura. As variáveis somente leitura têm nomes que começam com um caractere de sublinhado (_).

  • Valores de variável de sequência de tarefas podem diferenciar maiúsculas de minúsculas, dependendo do uso do valor. Na maioria dos casos, os valores de variável de sequência de tarefas não diferenciam maiúsculas de minúsculas. Uma variável que inclui uma senha diferencia maiúsculas de minúsculas.

Definir variável de sequência de tarefas

Use esta etapa na sequência de tarefas para definir uma única variável para um único valor.

Para obter mais informações, consulte Definir variável de sequência de tarefas.

Definir variáveis dinâmicas

Use esta etapa na sequência de tarefas para definir uma ou mais variáveis da sequência de tarefas. Você define regras nesta etapa para determinar quais variáveis e valores usar.

Para obter mais informações, consulte Definir variáveis dinâmicas.

Executar Script do PowerShell

Use esta etapa na sequência de tarefas para usar um script do PowerShell para definir uma variável de sequência de tarefas.

Você pode especificar um nome de script de um pacote ou inserir diretamente um script do PowerShell na etapa. Em seguida, use a propriedade step para Output para variável de sequência de tarefas para salvar a saída do script em uma variável de sequência de tarefas personalizada.

Para obter mais informações sobre essa etapa, consulte Executar script do PowerShell.

Observação

Você também pode usar um script do PowerShell para definir uma ou mais variáveis com o objeto TSEnvironment . Para obter mais informações, consulte Como usar variáveis em uma sequência de tarefas em execução no SDK do Configuration Manager.

Exemplo de cenário com a etapa Executar Script do PowerShell

Seu ambiente tem usuários em vários países/regiões, portanto, você deseja consultar o idioma do sistema operacional para definir como condição em várias etapas do sistema operacional de aplicação específicas do idioma.

  1. Adicione uma instância de Executar Script do PowerShell à sequência de tarefas antes das etapas de Aplicar SO .

  2. Use a opção para inserir um script do PowerShell para especificar o seguinte comando:

    (Get-Culture).TwoLetterISOLanguageName

    Para obter mais informações sobre o cmdlet, consulte Get-Culture. Para obter mais informações sobre os nomes de idiomas ISO de duas letras, consulte Lista de códigos ISO 639-1.

  3. Para a opção de Saída para variável de sequência de tarefas, especifique CurrentOSLanguage.

    Captura de tela do exemplo de Executar etapa de Script do PowerShell

  4. Na etapa Aplicar SO para a imagem em inglês, crie a seguinte condição: Task Sequence Variable CurrentOSLanguage equals "en"

    Captura de tela da condição de exemplo na etapa Aplicar SO

    Dica

    Para obter mais informações sobre como criar uma condição em uma etapa, consulte Como acessar variáveis - Condição da etapa.

  5. Salve e implante a sequência de tarefas.

Quando a etapa Executar Script do PowerShell é executada em um dispositivo com a versão em inglês do Windows, o comando retorna o valor en. Em seguida, ele salva esse valor na variável personalizada. Quando a etapa Aplicar SO para a imagem em inglês é executada no mesmo dispositivo, a condição é avaliada como verdadeira. Se você tiver várias instâncias da etapa Aplicar SO para idiomas diferentes, a sequência de tarefas executará dinamicamente a etapa que corresponde ao idioma do sistema operacional.

Variáveis de coleção e dispositivo

Você pode definir variáveis de sequência de tarefas personalizadas para dispositivos e coleções. As variáveis que você define para um dispositivo são chamadas de variáveis de sequência de tarefas por dispositivo. As variáveis definidas para uma coleção são chamadas de variáveis de sequência de tarefas por coleção. Se houver um conflito, as variáveis por dispositivo terão precedência sobre as variáveis por coleção. Esse comportamento significa que as variáveis de sequência de tarefas atribuídas a um dispositivo específico têm automaticamente uma prioridade mais alta do que as variáveis atribuídas à coleção que contém o dispositivo.

Por exemplo, o dispositivo XYZ é membro da coleção ABC. Você atribui MyVariable à coleção ABC com um valor de 1. Você também atribui MyVariable ao dispositivo XYZ com um valor de 2. A variável atribuída a XYZ tem prioridade mais alta do que a variável atribuída à coleção ABC. Quando uma sequência de tarefas com essa variável é executada em XYZ, MyVariable tem um valor de 2.

Você pode ocultar variáveis por dispositivo e por coleção para que elas não fiquem visíveis no console do Configuration Manager. Quando você usa a opção Não exibir esse valor no console do Configuration Manager, o valor da variável não é exibido no console. O arquivo de log de sequência de tarefas (smsts.log) ou o depurador de sequência de tarefas também não mostrará o valor da variável. A variável ainda pode ser usada pela sequência de tarefas quando ela é executada. Se você não quiser mais que essas variáveis sejam ocultadas, exclua-as primeiro. Em seguida, redefina as variáveis sem selecionar a opção para ocultá-las.

Aviso

Se você incluir variáveis na linha de comando da etapa Executar Linha de Comando , o arquivo de log da sequência de tarefas exibirá a linha de comando completa, incluindo os valores das variáveis. Para evitar que dados potencialmente confidenciais apareçam no arquivo de log, defina a variável de sequência de tarefas OSDDoNotLogCommand como TRUE.

Você pode gerenciar variáveis por dispositivo em um site primário ou em um site de administração central. O Configuration Manager não dá suporte a mais de 1.000 variáveis atribuídas para um dispositivo.

Importante

Ao usar variáveis por coleção para sequências de tarefas, considere os seguintes comportamentos:

  • As alterações nas coleções são sempre replicadas em toda a hierarquia. Quaisquer alterações feitas nas variáveis da coleção se aplicam não apenas aos membros do site atual, mas a todos os membros da coleção em toda a hierarquia.

  • Quando você exclui uma coleção, essa ação também exclui as variáveis de sequência de tarefas que você configurou para a coleção.

Criar variáveis de sequência de tarefas para um dispositivo

  1. No console do Configuration Manager, acesse o espaço de trabalho Ativos e Conformidade e selecione o nó Dispositivos.

  2. Selecione o dispositivo de destino e selecione Propriedades.

  3. Na caixa de diálogo Propriedades , alterne para a guia Variáveis .

  4. Para cada variável que você deseja criar, selecione o ícone Novo . Especifique o Nome e o Valor da variável de sequência de tarefas. Se você quiser ocultar a variável para que ela não fique visível no console do Configuration Manager, selecione a opção Não exibir esse valor no console do Configuration Manager.

  5. Depois de adicionar todas as variáveis às propriedades do dispositivo, selecione OK.

Criar variáveis de sequência de tarefas para uma coleção

  1. No console do Configuration Manager, acesse o espaço de trabalho Ativos e Conformidade e selecione o nó Coleções de Dispositivos. Selecione a coleção de destino e escolha Propriedades.

  2. Na caixa de diálogo Propriedades , alterne para a guia Variáveis da coleção .

  3. Para cada variável que você deseja criar, selecione o ícone Novo . Especifique o Nome e o Valor da variável de sequência de tarefas. Se você quiser ocultar a variável para que ela não fique visível no console do Configuration Manager, selecione a opção Não exibir esse valor no console do Configuration Manager.

  4. Opcionalmente, especifique a prioridade a ser usada pelo Configuration Manager quando as variáveis de sequência de tarefas forem avaliadas.

  5. Depois de adicionar todas as variáveis às propriedades da coleção, selecione OK.

Objeto COM de Ambiente de TSEnvironment

Para trabalhar com variáveis de um script, use o objeto TSEnvironment .

Para obter mais informações, consulte Como usar variáveis em uma sequência de tarefas em execução no SDK do Configuration Manager.

Comando de pré-inicialização

O comando prestart é um script ou executável que é executado no Windows PE antes que o usuário selecione a sequência de tarefas. O comando prestart pode consultar uma variável ou solicitar informações ao usuário e salvá-las no ambiente. Use o objeto COM TSEnvironment para ler e gravar variáveis do comando prestart.

Para obter mais informações, consulte Comandos de pré-início para mídia de sequência de tarefas.

Assistente de Sequência de Tarefas

Depois de selecionar uma sequência de tarefas na janela do Assistente de Sequência de Tarefas, a página para editar variáveis de sequência de tarefas inclui um botão Editar . Você pode usar atalhos de teclado acessíveis para editar as variáveis. Essa alteração ajuda nos casos em que um mouse não está disponível.

Assistente de Mídia de Sequência de Tarefas

Especifique variáveis para sequências de tarefas que são executadas a partir da mídia. Ao usar a mídia para implantar o sistema operacional, você adiciona as variáveis de sequência de tarefas e especifica seus valores ao criar a mídia. As variáveis e seus valores são armazenados na mídia.

Observação

As sequências de tarefas são armazenadas em mídias autônomas. No entanto, todos os outros tipos de mídia, como mídia pré-configurada, recuperam a sequência de tarefas de um ponto de gerenciamento.

Ao executar uma sequência de tarefas a partir da mídia, você pode adicionar uma variável na página Personalização do assistente.

Use as variáveis de mídia no lugar de variáveis por coleção ou por computador. Se a sequência de tarefas estiver sendo executada a partir de mídia, as variáveis por computador e por coleção não se aplicarão e não serão usadas.

Dica

A sequência de tarefas grava a ID do pacote e a linha de comando de pré-início no arquivo CreateTSMedia.log no computador que executa o console Configuration Manager. Esse arquivo de log inclui o valor para quaisquer variáveis de sequência de tarefas. Revise este arquivo de log para verificar o valor das variáveis de sequência de tarefas.

Para obter mais informações, consulte Criar mídia de sequência de tarefas.

Como acessar variáveis

Depois de especificar a variável e seu valor usando um dos métodos da seção anterior, use-os em suas sequências de tarefas. Por exemplo, acesse valores padrão para variáveis de sequência de tarefas internas ou condicione uma etapa ao valor de uma variável.

Use os seguintes métodos para acessar valores de variáveis no ambiente de sequência de tarefas:

Usar em uma etapa

Especifique um valor de variável para uma configuração em uma etapa de sequência de tarefas. No editor de sequência de tarefas, edite a etapa e especifique o nome da variável como o valor do campo. Delimite o nome da variável entre sinais de porcentagem (%).

Por exemplo, use o nome da variável como parte do campo Linha de Comando da etapa Executar Linha de Comando . A linha de comando a seguir grava o nome do computador em um arquivo de texto.

cmd.exe /c echo %_SMSTSMachineName% > C:\File.txt

Condição da etapa

Use variáveis de sequência de tarefas internas ou personalizadas como parte de uma condição em uma etapa ou grupo. A sequência de tarefas avalia o valor da variável antes de executar a etapa ou o grupo.

Para adicionar uma condição que avalia um valor de variável, siga as seguintes etapas:

  1. No editor de sequência de tarefas, selecione a etapa ou o grupo ao qual você deseja adicionar a condição.

  2. Alterne para a guia Opções da etapa ou grupo. Clique em Adicionar Condição e selecione Variável de Sequência de Tarefas.

  3. Na caixa de diálogo Variável de Sequência de Tarefas , especifique as seguintes configurações:

    • Variable: o nome da variável. Por exemplo, _SMSTSInWinPE.

    • Condição: a condição para avaliar o valor da variável. As seguintes condições estão disponíveis:

      • Saídas
      • Não existe
      • Igual a
      • Não é igual a
      • Maior que
      • Maior ou igual a
      • Menor que
      • Menor ou igual a
      • Como (dá suporte a curingas de * e ?)
      • Não é diferente (versão 2103 ou posterior)

    • Valor: O valor da variável a ser marcada. Por exemplo, false.

Os três exemplos acima formam uma condição comum para testar se a sequência de tarefas está sendo executada de uma imagem de inicialização no Windows PE:

Variável de Sequência de Tarefas_SMSTSInWinPE equals "false"

Consulte essa condição no grupo Captura Files e Configurações do modelo de sequência de tarefas padrão para instalar uma imagem de sistema operacional existente.

Para obter mais informações sobre condições, consulte Editor de sequência de tarefas - Condições.

Script personalizado

Ler e gravar variáveis usando o objeto COM Microsoft.SMS.TSEnvironment enquanto a sequência de tarefas está em execução.

O exemplo de Windows PowerShell a seguir consulta a variável _SMSTSLogPath para obter o local do log atual. O script também define uma variável personalizada.

# Create an object to access the task sequence environment
$tsenv = New-Object -ComObject Microsoft.SMS.TSEnvironment

# Query the environment to get an existing variable
# Set a variable for the task sequence log path
$LogPath = $tsenv.Value("_SMSTSLogPath")

# Or, convert all of the variables currently in the environment to PowerShell variables
$tsenv.GetVariables() | % { Set-Variable -Name "$_" -Value "$($tsenv.Value($_))" }

# Write a message to a log file
Write-Output "Hello world!" | Out-File -FilePath "$LogPath\mylog.log" -Encoding "Default" -Append

# Set a custom variable "startTime" to the current time
$tsenv.Value("startTime") = (Get-Date -Format HH:mm:ss) + ".000+000"

Arquivo de respostas de configuração do Windows

O arquivo de respostas de instalação do Windows que você fornece pode ter variáveis de sequência de tarefas inseridas. Use o formato %varname%, onde varname é o nome da variável. A etapa de instalação do Windows e ConfigMgr substitui a cadeia de caracteres do nome da variável pelo valor da variável real. Essas variáveis de sequência de tarefas inseridas não podem ser usadas em campos somente numéricos em um arquivo de resposta unattend.xml.

Para obter mais informações, consulte Configurar o Windows e o ConfigMgr.

Confira também

  • Last updated on