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

Importante

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

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

Observação

As tarefas de inicialização não são aplicáveis às Máquinas Virtuais, apenas às 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 executadas antes do início das funções. O arquivo ServiceDefinition.csdef define tarefas de inicialização usando o elemento Task dentro do elemento Startup . Com frequência, as tarefas de inicialização são arquivos em lotes, mas elas também podem ser aplicativos de console ou arquivos em lotes 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 transmitir informações para fora 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 arquivos podem ser gravados no armazenamento. 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 se resolve para o diretório C:\Resources\temp\[guid].[rolename]\RoleTemp ao executar na nuvem.

As tarefas de inicialização também podem ser executadas várias vezes entre as reinicializações. Por exemplo, a tarefa de inicialização é executada cada vez que a função é reciclada, e as reciclagens de função nem sempre incluirão uma reinicialização. As tarefas de inicialização devem ser gravadas de uma maneira que permita que sejam executadas diversas 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 errorlevel diferente de zero, o papel falhará ao iniciar.

Ordem de inicialização de função

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

1. A instância é marcada como Inicialização 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 de primeiro plano são iniciadas de forma assíncrona, paralelamente à tarefa de inicialização.

     Aviso

     O IIS pode não estar totalmente configurado durante a fase de tarefas de inicialização no processo de inicialização e, portanto, os dados específicos da função podem não estar disponíveis. Tarefas de inicialização que exigem dados específicos de função devem usar Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.OnStart.

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

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

5. A instância é marcada como Pronto 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 de 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 lote 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

Observação

No Visual Studio, a propriedade Copy to Output Directory do arquivo de lote de inicialização deve ser definida como Copiar Sempre para ter certeza de que o arquivo de 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 dos atributos da tarefa

O seguinte 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.
• Geralmente, esse atributo é o nome de um arquivo em lotes .cmd ou .bat.
• A tarefa está relacionada à pasta Bin do AppRoot para a implantação. As variáveis de ambiente não são expandidas para a determinação do caminho e do arquivo da tarefa. Se a expansão de ambiente for necessária, você poderá criar um script .cmd pequeno que chame sua tarefa de inicialização.
• Pode ser um aplicativo de console ou um arquivo em lote 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 do usuário são usados.
• elevado
  A tarefa de inicialização é executada com privilégios de administrador. Esse privilégio permite que as tarefas de inicialização instalem programas, façam alterações de configuração no IIS, executem alterações no Registro e outras tarefas no nível de administrador sem aumentar o nível de privilégio da própria função.

Observação

O nível de privilégio de uma tarefa de inicialização não precisa ser igual ao da própria função.

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 nenhuma tarefa de inicialização simples a ser executada, então a função se inicia.

  Observação

  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 própria função, não serão iniciadas.

  Para garantir que o arquivo em lotes termine com um errorlevel igual a zero, execute o comando EXIT /B 0 ao final do processo do arquivo em lotes.

• fundo
  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 segundo plano é que uma tarefa em primeiro plano evita que a função recicle ou finalize até que a tarefa for concluída. 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 contenha 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.

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

Variáveis de ambiente estático usam o atributo de valor 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 "preparo" ou "produção" para executar ações de inicialização diferentes com base no valor da variável de ambiente StagingOrProduction .

Variáveis de ambiente baseadas em membros da classe RoleEnvironment não usam o atributo de valor do elemento Variable . Em vez disso, o elemento filho RoleInstanceValue , com o valor de atributo XPath apropriado, é usado para criar uma variável de ambiente com base em um membro específico da classe RoleEnvironment . Os valores do 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 em execução no emulador de computação e "false" ao ser executada na nuvem, use os seguintes elementos Variável 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óximas etapas

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

Empacote seu Serviço de Cloud.