Como configurar e executar tarefas de inicialização para um serviço de nuvemHow to configure and run startup tasks for a cloud service

Você pode usar as tarefas de inicialização para executar operações antes do início de uma função.You can use startup tasks to perform operations before a role starts. As operações que talvez você queira executar incluem a instalação de um componente, o registro de componentes COM, a configuração de chaves do Registro ou o início de um processo de longa duração.Operations that you might want to perform include installing a component, registering COM components, setting registry keys, or starting a long running process.

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.Startup tasks are not applicable to Virtual Machines, only to Cloud Service Web and Worker roles.

Como funcionam as tarefas de inicializaçãoHow startup tasks work

As tarefas de inicialização são as ações executadas antes de suas funções começarem e são definidas no arquivo ServiceDefinition.csdef usando o elemento Tarefa dentro do elemento Startup.Startup tasks are actions that are taken before your roles begin and are defined in the ServiceDefinition.csdef file by using the Task element within the Startup element. 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.Frequently startup tasks are batch files, but they can also be console applications, or batch files that start PowerShell scripts.

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.Environment variables pass information into a startup task, and local storage can be used to pass information out of a startup task. 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 local que poderá então ser lido posteriormente por suas funções.For example, an environment variable can specify the path to a program you want to install, and files can be written to local storage that can then be read later by your roles.

Sua tarefa de inicialização pode registrar informações e erros no diretório especificado pela variável de ambiente TEMP .Your startup task can log information and errors to the directory specified by the TEMP environment variable. Durante a tarefa de inicialização, a variável de ambiente TEMP determina o diretório C:\Resources\temp\[guid].[nomefunção]\RoleTemp ao executar na nuvem.During the startup task, the TEMP environment variable resolves to the C:\Resources\temp\[guid].[rolename]\RoleTemp directory when running on the cloud.

As tarefas de inicialização também podem ser executadas várias vezes entre as reinicializações.Startup tasks can also be executed several times between reboots. Por exemplo, a tarefa de inicialização será executada sempre que a função for reciclada, e as reciclagens de função nem sempre incluirão uma reinicialização.For example, the startup task will be run each time the role recycles, and role recycles may not always include a reboot. As tarefas de inicialização devem ser gravadas de uma maneira que permita que sejam executadas diversas vezes sem problemas.Startup tasks should be written in a way that allows them to run several times without problems.

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.Startup tasks must end with an errorlevel (or exit code) of zero for the startup process to complete. Se uma tarefa de inicialização terminar com um errorleveldiferente de zero, a função não será iniciada.If a startup task ends with a non-zero errorlevel, the role will not start.

Ordem de inicialização de funçãoRole startup order

A seguir, o procedimento de inicialização da função no Azure:The following lists the role startup procedure in Azure:

  1. A instância está marcada como Iniciando e não recebe o tráfego.The instance is marked as Starting and does not receive traffic.
  2. Todas as tarefas de inicialização são executadas de acordo com o atributo taskType .All startup tasks are executed according to their taskType attribute.

    • As tarefas simples são executadas de forma síncrona, uma de cada vez.The simple tasks are executed synchronously, one at a time.
    • As tarefas em segundo plano e primeiro plano são iniciadas de forma assíncrona, paralelas com a tarefa de inicialização.The background and foreground tasks are started asynchronously, parallel to the startup task.

      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.IIS may not be fully configured during the startup task stage in the startup process, so role-specific data may not be available. As tarefas de inicialização que exigem dados específicos da função devem usar Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.OnStart.Startup tasks that require role-specific data should use Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.OnStart.

  3. O processo de host da função é iniciado e o site é criado no IIS.The role host process is started and the site is created in IIS.
  4. O método Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.OnStart é chamado.The Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.OnStart method is called.
  5. A instância é marcada como Pronta e o tráfego é roteado para a instância.The instance is marked as Ready and traffic is routed to the instance.
  6. O método Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.Run é chamado.The Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.Run method is called.

Exemplo de uma tarefa de inicializaçãoExample of a startup task

As tarefas de inicialização são definidas no arquivo ServiceDefinition.csdef , no elemento Tarefa .Startup tasks are defined in the ServiceDefinition.csdef file, in the Task element. 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 será executada.The commandLine attribute specifies the name and parameters of the startup batch file or console command, the executionContext attribute specifies the privilege level of the startup task, and the taskType attribute specifies how the task will be executed.

Neste exemplo, uma variável de ambiente, MyVersionNumber, é criada para a tarefa de inicialização e definida para o valor "1.0.0.0".In this example, an environment variable, MyVersionNumber, is created for the startup task and set to the value "1.0.0.0".

ServiceDefinition.csdef: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.In the following example, the Startup.cmd batch file writes the line "The current version is 1.0.0.0" to the StartupLog.txt file in the directory specified by the TEMP environment variable. A linha EXIT /B 0 garante que a tarefa de inicialização termine com um errorlevel zero.The EXIT /B 0 line ensures that the startup task ends with an errorlevel of 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 (approot\bin para as funções Web e approot para as funções de trabalho).In Visual Studio, the Copy to Output Directory property for your startup batch file should be set to Copy Always to be sure that your startup batch file is properly deployed to your project on Azure (approot\bin for Web roles, and approot for worker roles).

Descrição dos atributos da tarefaDescription of task attributes

A seguir, a descrição dos atributos do elemento Task do arquivo ServiceDefinition.csdef :The following describes the attributes of the Task element in the ServiceDefinition.csdef file:

commandLine - especifica a linha de comando para a tarefa de inicialização:commandLine - Specifies the command line for the startup task:

  • O comando, com parâmetros de linha de comando opcionais, que inicia a tarefa de inicialização.The command, with optional command line parameters, which begins the startup task.
  • Geralmente, esse é o nome do arquivo de um arquivo em lotes .cmd ou .bat.Frequently this is the filename of a .cmd or .bat batch file.
  • A tarefa é relativa à pasta Bin do \AppRoot da implantação.The task is relative to the AppRoot\Bin folder for the deployment. As variáveis de ambiente não são expandidas para a determinação do caminho e do arquivo da tarefa.Environment variables are not expanded in determining the path and file of the task. Se a expansão de ambiente for necessária, você poderá criar um script .cmd pequeno que chame sua tarefa de inicialização.If environment expansion is required, you can create a small .cmd script that calls your startup task.
  • Pode ser um aplicativo de console ou um arquivo em lotes que inicie um script do PowerShell.Can be a console application or a batch file that starts a PowerShell script.

executionContext - especifica o nível de privilégio para a tarefa de inicialização.executionContext - Specifies the privilege level for the startup task. O nível de privilégio pode ser limitado ou elevado:The privilege level can be limited or elevated:

  • limitadolimited
    A tarefa de inicialização é executada com os mesmos privilégios da função.The startup task runs with the same privileges as the role. Quando o atributo executionContext do elemento Tempo de execução também é limitado, os privilégios do usuário são usados.When the executionContext attribute for the Runtime element is also limited, then user privileges are used.
  • elevadoelevated
    A tarefa de inicialização é executada com privilégios de administrador.The startup task runs with administrator privileges. Isso 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.This allows startup tasks to install programs, make IIS configuration changes, perform registry changes, and other administrator level tasks, without increasing the privilege level of the role itself.

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.The privilege level of a startup task does not need to be the same as the role itself.

taskType - especifica a maneira como uma tarefa de inicialização é executada.taskType - Specifies the way a startup task is executed.

  • simplesssimple
    As tarefas são executadas de forma síncrona, uma de cada vez, na ordem especificada no arquivo ServiceDefinition.csdef .Tasks are executed synchronously, one at a time, in the order specified in the ServiceDefinition.csdef file. Quando uma tarefa de inicialização simplestermina com um errorlevel zero, a próxima tarefa de inicialização simples é executada.When one simple startup task ends with an errorlevel of zero, the next simple startup task is executed. Se não houver nenhum mais tarefas de inicialização simples a serem executadas, então a função será iniciada.If there are no more simple startup tasks to execute, then the role itself will be started.

    Observação

    Se a tarefa simples terminar com um errorlevel diferente de zero, a instância será bloqueada.If the simple task ends with a non-zero errorlevel, the instance will be blocked. As tarefas de inicialização simples subsequentes , e a própria função, não serão iniciadas.Subsequent simple startup tasks, and the role itself, will not start.

    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.To ensure that your batch file ends with an errorlevel of zero, execute the command EXIT /B 0 at the end of your batch file process.

  • segundo planobackground
    As tarefas são executadas de forma assíncrona, em paralelo com a inicialização da função.Tasks are executed asynchronously, in parallel with the startup of the role.
  • primeiro planoforeground
    As tarefas são executadas de forma assíncrona, em paralelo com a inicialização da função.Tasks are executed asynchronously, in parallel with the startup of the role. 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 seja concluída.The key difference between a foreground and a background task is that a foreground task prevents the role from recycling or shutting down until the task has ended. As tarefas em segundo plano não têm essa restrição.The background tasks do not have this restriction.

Variáveis de ambienteEnvironment variables

As variáveis de ambiente são uma maneira de passar informações para uma tarefa de inicialização.Environment variables are a way to pass information to a startup task. 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 usará, ou configurações para controlar recursos de sua tarefa de inicialização.For example, you can put the path to a blob that contains a program to install, or port numbers that your role will use, or settings to control features of your startup task.

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 .There are two kinds of environment variables for startup tasks; static environment variables and environment variables based on members of the RoleEnvironment class. Ambas estão na seção Ambiente do arquivo ServiceDefinition.csdef e usam o elemento Variable e o atributo name.Both are in the Environment section of the ServiceDefinition.csdef file, and both use the Variable element and name attribute.

As variáveis de ambiente estáticas usam o atributo value do elemento Variable .Static environment variables uses the value attribute of the Variable element. O exemplo acima cria a variável de ambiente MyVersionNumber que tem um valor estático "1.0.0.0".The example above creates the environment variable MyVersionNumber which has a static value of "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.Another example would be to create a StagingOrProduction environment variable which you can manually set to values of "staging" or "production" to perform different startup actions based on the value of the StagingOrProduction environment variable.

As variáveis de ambiente baseadas nos membros da classe RoleEnvironment não usam o atributo value do elemento Variable .Environment variables based on members of the RoleEnvironment class do not use the value attribute of the Variable element. 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.Instead, the RoleInstanceValue child element, with the appropriate XPath attribute value, are used to create an environment variable based on a specific member of the RoleEnvironment class. Os valores do atributo XPath para acessar os diversos valores RoleEnvironment podem ser encontrados aqui.Values for the XPath attribute to access various RoleEnvironment values can be found here.

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 :For example, to create an environment variable that is "true" when the instance is running in the compute emulator, and "false" when running in the cloud, use the following Variable and RoleInstanceValue elements:

<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 etapasNext steps

Saiba como executar algumas tarefas de inicialização comuns com seu Serviço de Nuvem.Learn how to perform some common startup tasks with your Cloud Service.

Empacote seu Serviço de Nuvem.Package your Cloud Service.