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. As 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 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 de ServiceDefinition.csdef define tarefas de inicialização usando a Tarefa elemento dentro do elemento Inicialização. 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 resolve ao diretório C:\Resources\temp\[guid].[rolename]\RoleTemp quando executado 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 que a função for 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 errorlevel (ou código de saída) zero para que o processo de inicialização seja concluído. Se uma tarefa de inicialização terminar com um nível de error diferente de zero, nível de erro a função não será iniciada.

Ordem de inicialização de função

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

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

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

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

   • As tarefas de segundo plano e em primeiro plano são iniciadas de forma assíncrona, paralelas a 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. 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 da função é 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 Pronta 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 Tarefa . O atributo commandLine especifica o nome e os parâmetros do arquivo de inicialização em lote ou do comando de 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 para 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 linha EXIT /B 0 garante que a tarefa de inicialização termine com um errorlevel 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 inicialização em lote deve ser definida para Copy Always para verificar se o arquivo de inicialização em lote está implantado corretamente em seu projeto no Azure (approotbin para as funções Web e approot para as funções de trabalho).

Descrição dos atributos da tarefa

A seguir, a descrição dos atributos do elemento Task do 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 do arquivo de um arquivo em lotes .cmd ou .bat.
• A tarefa é relativa à pasta Bin do AppRoot da 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 lotes que inicie 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 do 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.

• simpless
  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 simplestermina com um errorlevel zero, a próxima tarefa de inicialização simples é executada. Se não houver nenhum mais tarefas de inicialização simples a serem executadas, então a função é iniciada.

  Observação

  Se a tarefa simples terminar com um errorlevel 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 lote terminará com um errorlevel zero, execute o comando EXIT /B 0 no final do processo do arquivo em lote.

• segundo plano
  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áticas e variáveis de ambiente baseadas nos membros da classe RoleEnvironment . Ambas 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áticas usam o atributo valor do elemento Variable. O exemplo precedente cria a variável de ambiente MyVersionNumber que tem um valor estático "1.0.0.0". Outro exemplo seria criar uma variável de ambiente StagingOrProduction que você pode definir manualmente para os valores de "preparo" ou "produção" para executar ações diferentes de inicialização com base no valor da variável de ambiente StagingOrProduction.

As variáveis de ambiente baseadas nos membros da classe RoleEnvironment não usam o atributo valor do elemento Variável. Em vez disso, o elemento-filho RoleInstanceValue, com o devido valor do atributo XPath, é 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 os diversos valores RoleEnvironment podem ser encontrados aqui.

Por exemplo, para criar uma variável de ambiente "true" quando a instância está em execução no emulador de computação, e "false" quando em execução 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óximas etapas

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

Empacote seu Serviço de Nuvem.