Como configurar e executar tarefas de inicialização para um Serviço de Nuvem do Azure (clássico)

Importante

Os Serviços na Nuvem (clássicos) foram preteridos para todos os clientes a partir de 1º de setembro de 2024. Todas as implantações em execução existentes serão interrompidas e encerradas pela Microsoft e os dados serão perdidos permanentemente a partir de outubro de 2024. Novas implantações devem usar o novo modelo de implantação baseado no Azure Resource Manager Serviços de Nuvem do Azure (suporte estendido).

Você pode usar tarefas de inicialização para executar operações antes que uma função seja iniciada. As operações que você pode querer executar incluem a instalação de um componente, o registro de componentes COM (Component Object Model), a definição de chaves do Registro ou o início de um processo de longa execução.

Nota

As tarefas de inicialização não são aplicáveis a Máquinas Virtuais, apenas a funções Web e de Trabalho do Serviço de Nuvem.

Como funcionam as tarefas de inicialização

As tarefas de inicialização são ações realizadas antes do início de suas funções. O arquivo ServiceDefinition.csdef define tarefas de inicialização usando o elemento Task dentro do elemento Startup . Frequentemente, as tarefas de inicialização são arquivos em lote, mas também podem ser aplicativos de console ou arquivos em lote que iniciam scripts do PowerShell.

As variáveis de ambiente passam informações para uma tarefa de inicialização, e o armazenamento local pode ser usado para passar informações de uma tarefa de inicialização. Por exemplo, uma variável de ambiente pode especificar o caminho para um programa que você deseja instalar e os arquivos podem ser gravados no armazenamento local. A partir daí, suas funções podem ler os arquivos.

Sua tarefa de inicialização pode registrar informações e erros no diretório especificado pela variável de ambiente TEMP . Durante a tarefa de inicialização, a variável de ambiente TEMP é resolvida para C :\Resources\temp\[guid].[ rolename]\RoleTemp diretório quando executado na nuvem.

As tarefas de arranque também podem ser executadas várias vezes entre reinícios. Por exemplo, a tarefa de inicialização é executada sempre que a função é reciclada, e as reciclagens de função nem sempre podem incluir uma reinicialização. As tarefas de inicialização devem ser escritas de forma a permitir que sejam executadas várias vezes sem problemas.

As tarefas de inicialização devem terminar com um nível de erro (ou código de saída) de zero para que o processo de inicialização seja concluído. Se uma tarefa de inicialização terminar com um nível de erro diferente de zero, a função não será iniciada.

Ordem de inicialização da função

A seguir lista o procedimento de inicialização da função no Azure:

1. A instância está marcada como Iniciando e não recebe tráfego.

2. Todas as tarefas de inicialização são executadas de acordo com seu atributo taskType .

   • As tarefas simples são executadas de forma síncrona, uma de cada vez.

   • As tarefas em segundo plano e em primeiro plano são iniciadas de forma assíncrona, paralelamente à tarefa de inicialização.

     Aviso

     O IIS pode não estar totalmente configurado durante o estágio de tarefa de inicialização no processo de inicialização, portanto, dados específicos da função podem não estar disponíveis. As tarefas de inicialização que exigem dados específicos da função devem usar Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.OnStart.

3. O processo de host de função é iniciado e o site é criado no IIS (Serviços de Informações da Internet).

4. O método Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.OnStart é chamado.

5. A instância é marcada como Ready e o tráfego é roteado para a instância.

6. O método Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.Run é chamado.

Exemplo de uma tarefa de inicialização

As tarefas de inicialização são definidas no arquivo ServiceDefinition.csdef , no elemento Task . O atributo commandLine especifica o nome e os parâmetros do arquivo em lote de inicialização ou do comando do console, o atributo executionContext especifica o nível de privilégio da tarefa de inicialização e o atributo taskType especifica como a tarefa é executada.

Neste exemplo, uma variável de ambiente, MyVersionNumber, é criada para a tarefa de inicialização e definida como o valor "1.0.0.0".

ServiceDefinition.csdef:

<Startup>
    <Task commandLine="Startup.cmd" executionContext="limited" taskType="simple" >
        <Environment>
            <Variable name="MyVersionNumber" value="1.0.0.0" />
        </Environment>
    </Task>
</Startup>

No exemplo a seguir, o arquivo em lotes Startup.cmd grava a linha "A versão atual é 1.0.0.0" no arquivo StartupLog.txt no diretório especificado pela variável de ambiente TEMP. A EXIT /B 0 linha garante que a tarefa de inicialização termine com um nível de erro zero.

ECHO The current version is %MyVersionNumber% >> "%TEMP%\StartupLog.txt" 2>&1
EXIT /B 0

Nota

No Visual Studio, a propriedade Copiar para Diretório de Saída para seu arquivo em lote de inicialização deve ser definida como Copiar Sempre para ter certeza de que seu arquivo em lote de inicialização está implantado corretamente em seu projeto no Azure (approot\bin para funções Web e approot para funções de trabalho).

Descrição de atributos de tarefas

A seguir descreve os atributos do elemento Task no arquivo ServiceDefinition.csdef :

commandLine - Especifica a linha de comando para a tarefa de inicialização:

• O comando, com parâmetros de linha de comando opcionais, que inicia a tarefa de inicialização.
• Freqüentemente, esse atributo é o nome do arquivo de um .cmd ou .bat em lotes.
• A tarefa é relativa à pasta AppRoot\Bin para a implantação. As variáveis de ambiente não são expandidas para determinar o caminho e o arquivo da tarefa. Se a expansão do ambiente for necessária, você poderá criar um script de .cmd pequeno que chame sua tarefa de inicialização.
• Pode ser um aplicativo de console ou um arquivo em lotes que inicia um script do PowerShell.

executionContext - Especifica o nível de privilégio para a tarefa de inicialização. O nível de privilégio pode ser limitado ou elevado:

• limitado
  A tarefa de inicialização é executada com os mesmos privilégios da função. Quando o atributo executionContext para o elemento Runtime também é limitado, os privilégios de usuário são usados.
• elevado
  A tarefa de inicialização é executada com privilégios de administrador. Esses privilégios permitem que tarefas de inicialização instalem programas, façam alterações na configuração do IIS, executem alterações no Registro e outras tarefas de nível de administrador, sem aumentar o nível de privilégio da própria função.

Nota

O nível de privilégio de uma tarefa de inicialização não precisa ser o mesmo que a função em si.

taskType - Especifica a maneira como uma tarefa de inicialização é executada.

• simples
  As tarefas são executadas de forma síncrona, uma de cada vez, na ordem especificada no arquivo ServiceDefinition.csdef . Quando uma tarefa de inicialização simples termina com um nível de erro zero, a próxima tarefa de inicialização simples é executada. Se não houver mais tarefas de inicialização simples para executar, a função em si será iniciada.

  Nota

  Se a tarefa simples terminar com um nível de erro diferente de zero, a instância será bloqueada. As tarefas de inicialização simples subsequentes, e a função em si, não serão iniciadas.

  Para garantir que o arquivo em lotes termine com um nível de erro zero, execute o comando EXIT /B 0 no final do processo do arquivo em lotes.

• Contexto geral
  As tarefas são executadas de forma assíncrona, em paralelo com a inicialização da função.

• primeiro plano
  As tarefas são executadas de forma assíncrona, em paralelo com a inicialização da função. A principal diferença entre uma tarefa em primeiro plano e uma tarefa em segundo plano é que uma tarefa em primeiro plano impede que a função seja reciclada ou desligada até que a tarefa termine. As tarefas em segundo plano não têm essa restrição.

Variáveis de ambiente

As variáveis de ambiente são uma maneira de passar informações para uma tarefa de inicialização. Por exemplo, você pode colocar o caminho para um blob que contém um programa a ser instalado, ou números de porta que sua função usa, ou configurações para controlar recursos de sua tarefa de inicialização.

Existem dois tipos de variáveis de ambiente para tarefas de inicialização; variáveis de ambiente estático e variáveis de ambiente baseadas em membros da classe RoleEnvironment . Ambos estão na seção Environment do arquivo ServiceDefinition.csdef e usam o elemento Variable e o atributo name.

As variáveis de ambiente estático usam o atributo value do elemento Variable . O exemplo anterior cria a variável de ambiente MyVersionNumber que tem um valor estático de "1.0.0.0". Outro exemplo seria criar uma variável de ambiente StagingOrProduction , que você pode definir manualmente como valores de "staging" ou "production" para executar diferentes ações de inicialização com base no valor da variável de ambiente StagingOrProduction .

As variáveis de ambiente baseadas em membros da classe RoleEnvironment não usam o atributo value do elemento Variable . Em vez disso, o elemento filho RoleInstanceValue , com o valor apropriado do atributo XPath , é usado para criar uma variável de ambiente com base em um membro específico da classe RoleEnvironment . Os valores para o atributo XPath para acessar vários valores RoleEnvironment podem ser encontrados aqui.

Por exemplo, para criar uma variável de ambiente que seja "true" quando a instância estiver sendo executada no emulador de computação e "false" quando executada na nuvem, use os seguintes elementos Variable e RoleInstanceValue :

<Startup>
    <Task commandLine="Startup.cmd" executionContext="limited" taskType="simple">
        <Environment>

            <!-- Create the environment variable that informs the startup task whether it is running
                in the Compute Emulator or in the cloud. "%ComputeEmulatorRunning%"=="true" when
                running in the Compute Emulator, "%ComputeEmulatorRunning%"=="false" when running
                in the cloud. -->

            <Variable name="ComputeEmulatorRunning">
                <RoleInstanceValue xpath="/RoleEnvironment/Deployment/@emulated" />
            </Variable>

        </Environment>
    </Task>
</Startup>

Próximos passos

Saiba como executar algumas tarefas de inicialização comuns com seu Serviço de Nuvem.

Empacote seu serviço de nuvem.