Come configurare ed eseguire attività di avvio per un servizio cloudHow to configure and run startup tasks for a cloud service

È possibile usare le attività di avvio per eseguire operazioni prima dell'avvio di un ruolo.You can use startup tasks to perform operations before a role starts. Le operazioni che si possono eseguire sono l'installazione di un componente, la registrazione dei componenti COM, l'impostazione delle chiavi del Registro di sistema o l'avvio di un processo a esecuzione prolungata.Operations that you might want to perform include installing a component, registering COM components, setting registry keys, or starting a long running process.

Nota

Le attività di avvio non sono applicabili ai ruoli VM, ma solo ai ruoli Web e di lavoro del servizio cloud.Startup tasks are not applicable to Virtual Machines, only to Cloud Service Web and Worker roles.

Funzionamento delle attività di avvioHow startup tasks work

Le attività di avvio sono azioni effettuate prima dell'inizio dei ruoli e vengono definite nel file ServiceDefinition.csdef usando l'elemento Task all'interno dell'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. Spesso le attività di avvio sono file batch, ma possono essere anche applicazioni console o file batch tramite i quali si avviano script di PowerShell.Frequently startup tasks are batch files, but they can also be console applications, or batch files that start PowerShell scripts.

Le variabili di ambiente passano informazioni all'interno di un'attività di avvio e le risorse di archiviazione locale possono essere usate per il passaggio all'esterno di un'attività di avvio.Environment variables pass information into a startup task, and local storage can be used to pass information out of a startup task. In una variabile di ambiente può essere ad esempio specificato il percorso di un programma che si desidera installare e i file possono essere scritti nelle risorse di archiviazione locale e letti successivamente dai ruoli.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.

Con l'attività di avvio è possibile registrare informazioni ed errori nella directory specificata dalla variabile di ambiente TEMP .Your startup task can log information and errors to the directory specified by the TEMP environment variable. Durante l'attività di avvio, la variabile di ambiente TEMP viene risolta nella directory C:\Resources\temp\[guid].[nomeruolo]\RoleTemp nell'esecuzione nel cloud.During the startup task, the TEMP environment variable resolves to the C:\Resources\temp\[guid].[rolename]\RoleTemp directory when running on the cloud.

Le attività di avvio possono inoltre essere eseguite più volte tra un riavvio e l'altro.Startup tasks can also be executed several times between reboots. Ad esempio, l'attività di avvio viene eseguita a ogni riciclo del ruolo e tali ricicli non includono necessariamente un riavvio.For example, the startup task will be run each time the role recycles, and role recycles may not always include a reboot. Le attività di avvio devono essere scritte in modo da poter essere eseguite più volte senza problemi.Startup tasks should be written in a way that allows them to run several times without problems.

Le attività di avvio devono terminare con un valore di errorlevel (o codice di uscita) uguale a zero perché il processo di avvio possa essere completato.Startup tasks must end with an errorlevel (or exit code) of zero for the startup process to complete. Se l'attività di avvio termina con un valore di errorleveldiverso da zero, il ruolo non verrà avviato.If a startup task ends with a non-zero errorlevel, the role will not start.

Sequenza di avvio di un ruoloRole startup order

Di seguito è riportata la procedura di avvio di un ruolo in Azure:The following lists the role startup procedure in Azure:

  1. L'istanza viene contrassegnata con lo stato Avvio in corso e non riceve traffico.The instance is marked as Starting and does not receive traffic.
  2. Tutte le attività di avvio vengono eseguite in base al relativo attributo taskType .All startup tasks are executed according to their taskType attribute.

    • Le attività di tipo simple vengono eseguite in modo sincrono, una alla volta.The simple tasks are executed synchronously, one at a time.
    • Le attività di tipo background e foreground vengono avviate in modo asincrono, in parallelo all'attività di avvio.The background and foreground tasks are started asynchronously, parallel to the startup task.

      Avviso

      È possibile che IIS non sia stato configurato completamente nella fase delle attività di avvio del processo di avvio, pertanto potrebbero non essere disponibili dati specifici per il ruolo.IIS may not be fully configured during the startup task stage in the startup process, so role-specific data may not be available. Per le attività di avvio che richiedono dati specifici per il ruolo è necessario usare Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.OnStart.Startup tasks that require role-specific data should use Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.OnStart.

  3. Viene avviato il processo host del ruolo e il sito viene creato in IIS.The role host process is started and the site is created in IIS.
  4. Viene chiamato il metodo Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.OnStart .The Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.OnStart method is called.
  5. L'istanza viene contrassegnata con lo stato Pronto e il traffico viene indirizzato all'istanza.The instance is marked as Ready and traffic is routed to the instance.
  6. Viene chiamato il metodo Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.Run .The Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.Run method is called.

Esempio di attività di avvioExample of a startup task

Le attività di avvio vengono definite nel file ServiceDefinition.csdef nell'elemento Task .Startup tasks are defined in the ServiceDefinition.csdef file, in the Task element. L'attributo commandLine specifica il nome e i parametri del file batch o del comando di console di avvio, l'attributo executionContext specifica il livello di privilegio dell'attività di avvio e l'attributo taskType specifica la modalità di esecuzione dell'attività.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.

In questo esempio viene creata la variabile di ambiente MyVersionNumber per l'attività di avvio e il relativo valore viene impostato su "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>

Nell'esempio seguente il file batch Startup.cmd scrive la riga "The current version is 1.0.0.0" nel file StartupLog.txt nella directory specificata dalla variabile di 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. La riga EXIT /B 0 assicura che l'attività di avvio termini con un argomento errorlevel uguale a 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

Nota

In Visual Studio la proprietà Copia nella directory di output per il file batch di avvio deve essere impostata su Copia sempre per garantire la distribuzione corretta del file batch di avvio nel progetto in Azure (approot\bin per i ruoli Web e approot per i ruoli di lavoro).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).

Descrizione degli attributi di TaskDescription of task attributes

Di seguito vengono descritti gli attributi dell'elemento Task nel file ServiceDefinition.csdef :The following describes the attributes of the Task element in the ServiceDefinition.csdef file:

commandLine : specifica la riga di comando per l'attività di avvio, come indicato di seguito.commandLine - Specifies the command line for the startup task:

  • Il comando, con i parametri della riga di comando facoltativi, che inizia l'attività di avvio.The command, with optional command line parameters, which begins the startup task.
  • Questo è spesso il nome del file batch con estensione cmd o bat.Frequently this is the filename of a .cmd or .bat batch file.
  • L'attività è relativa alla cartella AppRoot\Bin per la distribuzione.The task is relative to the AppRoot\Bin folder for the deployment. Le variabili di ambiente non vengono espanse per determinare il percorso e il file dell'attività.Environment variables are not expanded in determining the path and file of the task. Se è necessaria l'espansione dell'ambiente, è possibile creare un piccolo script con estensione cmd con il quale richiamare l'attività di avvio.If environment expansion is required, you can create a small .cmd script that calls your startup task.
  • Può essere un'applicazione console o un file batch che avvia uno script di PowerShell.Can be a console application or a batch file that starts a PowerShell script.

executionContext : specifica il livello di privilegio per l'attività di avvio.executionContext - Specifies the privilege level for the startup task. Il livello di privilegio può essere limitato o elevato:The privilege level can be limited or elevated:

  • limitatolimited
    : l'attività di avvio viene eseguita con gli stessi privilegi del ruolo.The startup task runs with the same privileges as the role. Quando anche l'attributo executionContext dell'elemento Runtime è limitato, vengono usati i privilegi utente.When the executionContext attribute for the Runtime element is also limited, then user privileges are used.
  • elevatoelevated
    : l'attività di avvio viene eseguita con privilegi di amministratore.The startup task runs with administrator privileges. In questo modo attraverso le attività di avvio è possibile installare programmi, apportare modifiche alla configurazione di IIS, effettuare modifiche al Registro di sistema e altre attività a livello di amministratore senza aumentare il livello di privilegio del ruolo.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.

Nota

Il livello di privilegio dell'attività di avvio non deve essere necessariamente uguale al livello di privilegio del ruolo.The privilege level of a startup task does not need to be the same as the role itself.

taskType : specifica la modalità di esecuzione di un'attività di avvio.taskType - Specifies the way a startup task is executed.

  • simplesimple
    vengono eseguite in modo sincrono, una alla volta, nell'ordine specificato nel file ServiceDefinition.csdef .Tasks are executed synchronously, one at a time, in the order specified in the ServiceDefinition.csdef file. Quando un'attività di avvio simple termina con un valore errorlevel uguale a zero, viene eseguita l'attività di avvio simple successiva.When one simple startup task ends with an errorlevel of zero, the next simple startup task is executed. Se non sono presenti altre attività di avvio simple da eseguire, viene avviato il ruolo.If there are no more simple startup tasks to execute, then the role itself will be started.

    Nota

    Se l'attività simple termina con un valore errorlevel diverso da zero, l'istanza viene bloccata.If the simple task ends with a non-zero errorlevel, the instance will be blocked. Le successive attività di avvio simple e il ruolo non vengono avviati.Subsequent simple startup tasks, and the role itself, will not start.

    Per assicurarsi che il file batch termini con un valore errorlevel uguale a zero, eseguire il comando EXIT /B 0 al termine del processo del file batch.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.

  • backgroundbackground
    vengono eseguite in modo asincrono, in parallelo con l'avvio del ruolo.Tasks are executed asynchronously, in parallel with the startup of the role.
  • foregroundforeground
    vengono eseguite in modo asincrono, in parallelo con l'avvio del ruolo.Tasks are executed asynchronously, in parallel with the startup of the role. La differenza principale tra un'attività foreground e un'attività background è che l'attività foreground impedisce il riciclo o l'arresto del ruolo fino al termine dell'attività.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. Le attività background non prevedono questa restrizione.The background tasks do not have this restriction.

Variabili di ambienteEnvironment variables

Le variabili di ambiente costituiscono un modo per passare le informazioni a un'attività di avvio.Environment variables are a way to pass information to a startup task. È ad esempio possibile inserire il percorso di un BLOB contenente un programma da installare, i numeri di porta che verranno usati dal ruolo o impostazioni per controllare le funzionalità dell'attività di avvio.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.

Esistono due tipi di variabili di ambiente per le attività di avvio: le variabili di ambiente statiche e le variabili di ambiente basate sui membri della 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. Entrambi si trovano nella sezione Environment del file ServiceDefinition.csdef e per entrambi vengono usati l'elemento Variable e l'attributo name.Both are in the Environment section of the ServiceDefinition.csdef file, and both use the Variable element and name attribute.

Per le variabili di ambiente statiche viene usato l'attributo value dell'elemento Variable .Static environment variables uses the value attribute of the Variable element. Nell'esempio precedente viene creata la variabile di ambiente MyVersionNumber con un valore statico di "1.0.0.0".The example above creates the environment variable MyVersionNumber which has a static value of "1.0.0.0". Un altro esempio potrebbe essere la creazione di una variabile di ambiente StagingOrProduction impostabile manualmente sui valori "staging" o "production" per eseguire azioni di avvio diverse in base al valore della variabile di 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.

Per le variabili di ambiente basate sui membri della classe RoleEnvironment non viene usato l'attributo value dell'elemento Variable .Environment variables based on members of the RoleEnvironment class do not use the value attribute of the Variable element. Viene invece usato l'elemento figlio RoleInstanceValue, con il valore appropriato dell'attributo XPath, per creare una variabile di ambiente basata su un membro specifico della 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. I valori dell'attributo XPath per accedere ai diversi valori di RoleEnvironment sono disponibili qui.Values for the XPath attribute to access various RoleEnvironment values can be found here.

Per creare una variabile di ambiente che sia "true" se l'istanza è in esecuzione nell'emulatore di calcolo e "false" se è in esecuzione nel cloud, ad esempio, usare gli elementi Variable e RoleInstanceValue seguenti: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>

Passaggi successiviNext steps

Informazioni su come eseguire alcune attività di avvio comuni con il servizio cloud.Learn how to perform some common startup tasks with your Cloud Service.

Creare il pacchetto del servizio cloud.Package your Cloud Service.