クラウド サービスのスタートアップ タスクを構成して実行する方法How to configure and run startup tasks for a cloud service

ロールが開始する前に、スタートアップ タスクを使用して操作を実行できます。You can use startup tasks to perform operations before a role starts. 対象となる操作としては、コンポーネントのインストール、COM コンポーネントの登録、レジストリ キーの設定、実行時間の長いプロセスの開始などがあります。Operations that you might want to perform include installing a component, registering COM components, setting registry keys, or starting a long running process.

注意

スタートアップ タスクを使用できるのはクラウド サービス Web ロールと worker ロールのみであり、Virtual Machines には使用できません。Startup tasks are not applicable to Virtual Machines, only to Cloud Service Web and Worker roles.

スタートアップ タスクの動作方法How startup tasks work

スタートアップ タスクはロールが開始する前に実行されるアクションであり、ServiceDefinition.csdef ファイルにおいて Startup 要素の Task 要素を使用して定義されます。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. 多くの場合スタートアップ タスクはバッチ ファイルですが、コンソール アプリケーションまたは PowerShell スクリプトを開始するバッチ ファイルでもかまいません。Frequently startup tasks are batch files, but they can also be console applications, or batch files that start PowerShell scripts.

スタートアップ タスクに情報を渡すには環境変数を使用し、スタートアップ タスクから情報を受け取るにはローカル ストレージを使用します。Environment variables pass information into a startup task, and local storage can be used to pass information out of a startup task. たとえば、環境変数を使用してインストールするプログラムへのパスを指定でき、ファイルをローカル ストレージに書き込んでおいて後からロールで読み取ることができます。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.

スタートアップ タスクでは、 TEMP 環境変数によって指定されているディレクトリに情報およびエラーのログを記録できます。Your startup task can log information and errors to the directory specified by the TEMP environment variable. スタートアップ タスクがクラウドで実行されると、TEMP 環境変数は C:\Resources\temp\[GUID].[ロール名]\RoleTemp ディレクトリに解決されます。During the startup task, the TEMP environment variable resolves to the C:\Resources\temp\[guid].[rolename]\RoleTemp directory when running on the cloud.

再起動と再起動の間に、スタートアップ タスクを何回でも実行できます。Startup tasks can also be executed several times between reboots. たとえば、スタートアップ タスクはロールのリサイクルのたびに実行され、ロールのリサイクルには再起動が含まれない場合があります。For example, the startup task will be run each time the role recycles, and role recycles may not always include a reboot. 複数回実行されても問題がないように、スタートアップ タスクを作成する必要があります。Startup tasks should be written in a way that allows them to run several times without problems.

スタートアップ プロセスが完了するには、スタートアップ タスクが errorlevel (終了コード) ゼロで終了する必要があります。Startup tasks must end with an errorlevel (or exit code) of zero for the startup process to complete. スタートアップ タスクがゼロ以外の errorlevelで終了すると、ロールは開始しません。If a startup task ends with a non-zero errorlevel, the role will not start.

ロールのスタートアップ順序Role startup order

Azure でのロールのスタートアップ手順を次に示します。The following lists the role startup procedure in Azure:

  1. インスタンスは 開始中 とマークされ、トラフィックを受け取りません。The instance is marked as Starting and does not receive traffic.
  2. taskType 属性に従って、すべてのスタートアップ タスクが実行されます。All startup tasks are executed according to their taskType attribute.

    • 単純な タスクは、一度に 1 つずつ同期的に実行されます。The simple tasks are executed synchronously, one at a time.
    • background タスクと foreground タスクは、スタートアップ タスクと並列に非同期的に開始されます。The background and foreground tasks are started asynchronously, parallel to the startup task.

      警告

      IIS はスタートアップ プロセスのスタートアップ タスク ステージの間に完全に構成されない場合があるので、ロール固有のデータを使用できないことがあります。IIS may not be fully configured during the startup task stage in the startup process, so role-specific data may not be available. ロール固有のデータが必要なスタートアップ タスクは、 Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.OnStartを使用する必要があります。Startup tasks that require role-specific data should use Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.OnStart.

  3. ロール ホスト プロセスが開始され、サイトが IIS に作成されます。The role host process is started and the site is created in IIS.
  4. Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.OnStart メソッドが呼び出されます。The Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.OnStart method is called.
  5. インスタンスは 準備完了 とマークされ、トラフィックがインスタンスにルーティングされるようになります。The instance is marked as Ready and traffic is routed to the instance.
  6. Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.Run メソッドが呼び出されます。The Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.Run method is called.

スタートアップ タスクの例Example of a startup task

スタートアップ タスクは、ServiceDefinition.csdef ファイルの Task 要素で定義されています。Startup tasks are defined in the ServiceDefinition.csdef file, in the Task element. commandLine 属性では、スタートアップ バッチ ファイルまたはコンソール コマンドの名前とパラメーターを指定します。executionContext 属性では、スタートアップ タスクの特権レベルを指定します。taskType 属性では、タスクの実行方法を指定します。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.

この例では、環境変数 MyVersionNumber をスタートアップ タスク用に作成し、値を "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>

次の例では、 Startup.cmd バッチ ファイルは、TEMP 環境変数で指定されているディレクトリの StartupLog.txt ファイルに、"The current version is 1.0.0.0" という行を書き込みます。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. EXIT /B 0 の行は、 errorlevel が 0 でスタートアップ タスクが終了することを保証します。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

注意

スタートアップ バッチ ファイルが Azure のプロジェクトに適切にデプロイされるようにするには (Web ロールの場合は approot\bin、worker ロールの場合は approot)、Visual Studio で、スタートアップ バッチ ファイルの [出力ディレクトリにコピー] プロパティを [常にコピーする] に設定する必要があります。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).

タスクの属性の説明Description of task attributes

次に、 ServiceDefinition.csdef ファイルの ServiceDefinition.csdef 要素の属性について説明します。The following describes the attributes of the Task element in the ServiceDefinition.csdef file:

commandLine -スタートアップ タスクのコマンド ラインを指定します。commandLine - Specifies the command line for the startup task:

  • スタートアップ タスクを開始するコマンドと、オプションのコマンド ライン パラメーターです。The command, with optional command line parameters, which begins the startup task.
  • 通常、これは .cmd または .bat バッチ ファイルのファイル名です。Frequently this is the filename of a .cmd or .bat batch file.
  • タスクの位置は、デプロイメント用の AppRoot\Bin フォルダーに対する相対パスです。The task is relative to the AppRoot\Bin folder for the deployment. 環境変数は、タスクのパスとファイルを決定するときに展開されません。Environment variables are not expanded in determining the path and file of the task. 環境変数の展開が必要な場合は、スタートアップ タスクを呼び出す小さな .cmd スクリプトを作成できます。If environment expansion is required, you can create a small .cmd script that calls your startup task.
  • PowerShell スクリプトを開始するコンソール アプリケーションまたはバッチ ファイルを指定できます。Can be a console application or a batch file that starts a PowerShell script.

executionContext -スタートアップ タスクの特権レベルを指定します。executionContext - Specifies the privilege level for the startup task. 指定できる特権レベルは limited または elevated です。The privilege level can be limited or elevated:

  • limitedlimited
    スタートアップ タスクは、ロールと同じ特権で実行します。The startup task runs with the same privileges as the role. Runtime 要素の executionContext 属性も limited である場合は、ユーザー特権が使用されます。When the executionContext attribute for the Runtime element is also limited, then user privileges are used.
  • elevatedelevated
    スタートアップ タスクは、管理者特権で実行します。The startup task runs with administrator privileges. これにより、ロール自体の特権レベルを上げることなく、プログラムのインストール、IIS の構成の変更、レジストリの変更、その他の管理者レベル タスクを実行できます。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.

注意

スタートアップ タスクの特権レベルは、ロール自体と同じでなくてもかまいません。The privilege level of a startup task does not need to be the same as the role itself.

taskType -スタートアップ タスクを実行する方法を指定します。taskType - Specifies the way a startup task is executed.

  • 単純なsimple
    タスクは、 ServiceDefinition.csdef ファイルで指定されている順序で、一度に 1 つずつ、同期的に実行されます。Tasks are executed synchronously, one at a time, in the order specified in the ServiceDefinition.csdef file. ある simple スタートアップ タスクが 0 の errorlevel で終了すると、次の simple スタートアップ タスクが実行されます。When one simple startup task ends with an errorlevel of zero, the next simple startup task is executed. それ以上実行する simple スタートアップ タスクがない場合は、ロール自体が開始されます。If there are no more simple startup tasks to execute, then the role itself will be started.

    注意

    simple タスクが 0 以外の errorlevel で終了した場合は、インスタンスがブロックされます。If the simple task ends with a non-zero errorlevel, the instance will be blocked. 後続の simple スタートアップ タスクおよびロール自体は開始されません。Subsequent simple startup tasks, and the role itself, will not start.

    バッチ ファイルを 0 の errorlevel で確実に終了させるには、バッチ ファイル プロセスの最後で EXIT /B 0 コマンドを実行します。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
    タスクは、ロールのスタートアップと並行して、非同期的に実行されます。Tasks are executed asynchronously, in parallel with the startup of the role.
  • フォアグラウンドforeground
    タスクは、ロールのスタートアップと並行して、非同期的に実行されます。Tasks are executed asynchronously, in parallel with the startup of the role. foreground タスクと background タスクの重要な違いは、foreground タスクではタスクが終了するまでロールがリサイクルまたはシャットダウンされなくなることです。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. background タスクにはこのような制限はありません。The background tasks do not have this restriction.

環境変数Environment variables

環境変数は、スタートアップ タスクに情報を渡すための手段です。Environment variables are a way to pass information to a startup task. たとえば、インストールするプログラムを含む BLOB へのパス、ロールで使用するポート番号、スタートアップ タスクの機能を制御する設定などを設定できます。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.

スタートアップ タスクの環境変数には、静的環境変数と、 RoleEnvironment クラスのメンバーに基づく環境変数の 2 種類があります。There are two kinds of environment variables for startup tasks; static environment variables and environment variables based on members of the RoleEnvironment class. どちらも ServiceDefinition.csdef ファイルの Environment セクションにあり、Variable 要素と name 属性を使用します。Both are in the Environment section of the ServiceDefinition.csdef file, and both use the Variable element and name attribute.

静的環境変数は、 Variable 要素の Variable 属性を使用します。Static environment variables uses the value attribute of the Variable element. 上の例では、MyVersionNumber という名前の環境変数を作成し、静的な値 "1.0.0.0" を設定しています。The example above creates the environment variable MyVersionNumber which has a static value of "1.0.0.0". もう 1 つの例として、StagingOrProduction という名前の環境変数を作成し、手動で値 "staging" または "production" を設定して、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.

RoleEnvironment クラスに基づく環境変数では、 Variable 要素の Variable 属性は使用しません。Environment variables based on members of the RoleEnvironment class do not use the value attribute of the Variable element. 代わりに RoleInstanceValue 子要素と適切な xPath 属性値を使用して、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. さまざまな RoleEnvironment の値にアクセスするための XPath 属性の値については、こちらを参照してください。Values for the XPath attribute to access various RoleEnvironment values can be found here.

たとえば、インスタンスがコンピューティング エミュレーターで実行しているときは "true"、クラウドで実行しているときは "false" になる環境変数を作成するには、次の Variable 要素と 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>

次の手順Next steps

Cloud Service で 一般的なスタートアップ タスク を実行する方法を学習します。Learn how to perform some common startup tasks with your Cloud Service.

パッケージ化 します。Package your Cloud Service.