複数の環境のアプリケーション パラメーターを管理するManage application parameters for multiple environments

Azure Service Fabric クラスターは、1 台~ 数千台のコンピューターで作成することができます。You can create Azure Service Fabric clusters by using anywhere from one to many thousands of machines. アプリケーション バイナリは、変更を行わなくても、このようなさまざまな環境で実行することができますが、デプロイ先のコンピューターの台数に応じて、異なる方法でアプリケーションを構成する場合がよくあります。While application binaries can run without modification across this wide spectrum of environments, you often want to configure the application differently, depending on the number of machines you're deploying to.

簡単な例として、ステートレス サービスの InstanceCount について検討します。As a simple example, consider InstanceCount for a stateless service. Azure でアプリケーションを実行する場合は、通常、このパラメーターを特殊な値である "-1" に設定します。When you are running applications in Azure, you generally want to set this parameter to the special value of "-1". これにより、サービスがクラスター (または、配置の制約を設定している場合は、ノードの種類のすべてのノード) 内の各ノードで確実に実行されます。This configuration ensures that your service is running on every node in the cluster (or every node in the node type if you have set a placement constraint). ただし、この構成はコンピューターが 1 台のクラスターには適してしません。理由は、1 台のコンピューター上の同じエンドポイントで複数のプロセスをリッスン状態にしておくことができないからです。However, this configuration is not suitable for a single-machine cluster since you cannot have multiple processes listening on the same endpoint on a single machine. そこで、通常は InstanceCount を "1" に設定します。Instead, you typically set InstanceCount to "1".

環境固有のパラメーターを指定するSpecifying environment-specific parameters

この構成の問題に対するソリューションとして、パラメーター化された既定のサービス セットと、特定の環境のパラメーター値を含むアプリケーション パラメーター ファイルがあります。The solution to this configuration issue is a set of parameterized default services and application parameter files that fill in those parameter values for a given environment. 既定のサービスとアプリケーションのパラメーターは、アプリケーション マニフェストとサービス マニフェストで構成します。Default services and application parameters are configured in the application and service manifests. ServiceManifest.xml と ApplicationManifest.xml ファイルのスキーマ定義は、Service Fabric SDK およびツールと共に C:\Program Files\Microsoft SDKs\Service Fabric\schemas\ServiceFabricServiceModel.xsd にインストールされます。The schema definition for the ServiceManifest.xml and ApplicationManifest.xml files is installed with the Service Fabric SDK and tools to C:\Program Files\Microsoft SDKs\Service Fabric\schemas\ServiceFabricServiceModel.xsd.

既定のサービスDefault services

Service Fabric アプリケーションは、サービス インスタンスのコレクションで構成されています。Service Fabric applications are made up of a collection of service instances. 空のアプリケーションを作成してからすべてのサービス インスタンスを動的に作成することができますが、ほとんどのアプリケーションには、アプリケーションのインスタンス化の際に必ず作成されるコア サービス セットがあります。While it is possible for you to create an empty application and then create all service instances dynamically, most applications have a set of core services that should always be created when the application is instantiated. これらは "既定のサービス" と呼ばれます。These are referred to as "default services". これらはアプリケーション マニフェスト内に指定され、環境ごとの構成のプレース ホルダーは角かっこで囲まれます。They are specified in the application manifest, with placeholders for per-environment configuration included in square brackets:

  <DefaultServices>
      <Service Name="Stateful1">
          <StatefulService
              ServiceTypeName="Stateful1Type"
              TargetReplicaSetSize="[Stateful1_TargetReplicaSetSize]"
              MinReplicaSetSize="[Stateful1_MinReplicaSetSize]">

              <UniformInt64Partition
                  PartitionCount="[Stateful1_PartitionCount]"
                  LowKey="-9223372036854775808"
                  HighKey="9223372036854775807"
              />
        </StatefulService>
    </Service>
  </DefaultServices>

それぞれの名前付きパラメーターは、アプリケーション マニフェストの Parameters 要素内に定義する必要があります。Each of the named parameters must be defined within the Parameters element of the application manifest:

    <Parameters>
        <Parameter Name="Stateful1_MinReplicaSetSize" DefaultValue="3" />
        <Parameter Name="Stateful1_PartitionCount" DefaultValue="1" />
        <Parameter Name="Stateful1_TargetReplicaSetSize" DefaultValue="3" />
    </Parameters>

DefaultValue 属性では、特定の環境に対して具体的なパラメーターがない場合に使用される値が指定されます。The DefaultValue attribute specifies the value to be used in the absence of a more-specific parameter for a given environment.

注意

すべてのサービス インスタンス パラメーターが環境ごとの構成に適しているわけではありません。Not all service instance parameters are suitable for per-environment configuration. 上記の例で、サービスのパーティション分割構成の LowKey 値と HighKey 値は、サービスのすべてのインスタンスに対して明示的に定義されています。これは、パーティションの範囲が、環境ではなくデータ ドメインに応じて決まるからです。In the example above, the LowKey and HighKey values for the service's partitioning scheme are explicitly defined for all instances of the service since the partition range is a function of the data domain, not the environment.

環境ごとのサービス構成の設定Per-environment service configuration settings

Service Fabric アプリケーション モデルでは、実行時に読み取り可能なカスタム キー値ペアを含む構成パッケージをサービスに含めることができます。The Service Fabric application model enables services to include configuration packages that contain custom key-value pairs that are readable at run time. このような設定の値は環境ごとに区別することもできます。そのためには、アプリケーション マニフェストに ConfigOverride を指定します。The values of these settings can also be differentiated by environment by specifying a ConfigOverride in the application manifest.

Stateful1 サービスの Config\Settings.xml ファイル内に次の設定があると仮定します。Suppose that you have the following setting in the Config\Settings.xml file for the Stateful1 service:

  <Section Name="MyConfigSection">
     <Parameter Name="MaxQueueSize" Value="25" />
  </Section>

特定のアプリケーション/環境ペアのこの値をオーバーライドするには、アプリケーション マニフェストにサービス マニフェストをインポートするときに ConfigOverride を作成します。To override this value for a specific application/environment pair, create a ConfigOverride when you import the service manifest in the application manifest.

  <ConfigOverrides>
     <ConfigOverride Name="Config">
        <Settings>
           <Section Name="MyConfigSection">
              <Parameter Name="MaxQueueSize" Value="[Stateful1_MaxQueueSize]" />
           </Section>
        </Settings>
     </ConfigOverride>
  </ConfigOverrides>

このパラメーターは上記のように環境ごとに構成することができます。This parameter can then be configured by environment as shown above. そのためには、アプリケーション マニフェストのパラメーター セクションでこのパラメーターを宣言し、アプリケーション パラメーター ファイルに環境固有の値を指定します。You can do this by declaring it in the parameters section of the application manifest and specifying environment-specific values in the application parameter files.

注意

サービス構成設定の場合は、キーの値を設定できる場所が 3 箇所あります。サービス構成パッケージ、アプリケーション マニフェスト、およびアプリケーション パラメーター ファイルの 3 つです。In the case of service configuration settings, there are three places where the value of a key can be set: the service configuration package, the application manifest, and the application parameter file. Service Fabric は常に、まずアプリケーション パラメーター ファイル (指定されている場合) から選択し、次にアプリケーション マニフェスト、最後に構成パッケージの順に選択します。Service Fabric will always choose from the application parameter file first (if specified), then the application manifest, and finally the configuration package.

環境変数の設定と使用Setting and using environment variables

ServiceManifest.xml ファイルで環境変数を指定して設定した後、ApplicationManifest.xml ファイルで、それらをインスタンスごとにオーバーライドできます。You can specify and set environment variables in the ServiceManifest.xml file and then override these in the ApplicationManifest.xml file on a per instance basis. 次の例では、2 つの環境変数を示しています。1 つは値が設定され、もう 1 つはオーバーライドされます。The example below shows two environment variables, one with a value set and the other is overridden. アプリケーション パラメーターを使用する場合も、構成のオーバーライドに使用したのと同じ方法で環境変数の値を設定できます。You can use application parameters to set environment variables values in the same way that these were used for config overrides.

<?xml version="1.0" encoding="utf-8" ?>
<ServiceManifest Name="MyServiceManifest" Version="SvcManifestVersion1" xmlns="http://schemas.microsoft.com/2011/01/fabric" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Description>An example service manifest</Description>
  <ServiceTypes>
    <StatelessServiceType ServiceTypeName="MyServiceType" />
  </ServiceTypes>
  <CodePackage Name="MyCode" Version="CodeVersion1">
    <SetupEntryPoint>
      <ExeHost>
        <Program>MySetup.bat</Program>
      </ExeHost>
    </SetupEntryPoint>
    <EntryPoint>
      <ExeHost>
        <Program>MyServiceHost.exe</Program>
      </ExeHost>
    </EntryPoint>
    <EnvironmentVariables>
      <EnvironmentVariable Name="MyEnvVariable" Value=""/>
      <EnvironmentVariable Name="HttpGatewayPort" Value="19080"/>
    </EnvironmentVariables>
  </CodePackage>
  <ConfigPackage Name="MyConfig" Version="ConfigVersion1" />
  <DataPackage Name="MyData" Version="DataVersion1" />
</ServiceManifest>

ApplicationManifest.xml 内の環境変数をオーバーライドするには、ServiceManifest 内で、EnvironmentOverrides 要素を使用してコード パッケージを参照します。To override the environment variables in the ApplicationManifest.xml, reference the code package in the ServiceManifest with the EnvironmentOverrides element.

  <ServiceManifestImport>
    <ServiceManifestRef ServiceManifestName="FrontEndServicePkg" ServiceManifestVersion="1.0.0" />
    <EnvironmentOverrides CodePackageRef="MyCode">
      <EnvironmentVariable Name="MyEnvVariable" Value="mydata"/>
    </EnvironmentOverrides>
  </ServiceManifestImport>

指定したサービス インスタンスが作成されたら、環境変数にコードからアクセスできます。Once the named service instance is created you can access the environment variables from code. たとえば、C# では次のような操作が可能ですe.g. In C# you can do the following

    string EnvVariable = Environment.GetEnvironmentVariable("MyEnvVariable");

Service Fabric の環境変数Service Fabric environment variables

Service Fabric には、サービス インスタンスごとに設定された環境変数が組み込まれています。Service Fabric has built in environment variables set for each service instance. これらの環境変数を以下に示します。太字で示されている環境変数はサービスで使用するものであり、それ以外は Service Fabric ランタイムで使用されるものです。The full list of environment variables is below, where the ones in bold are the ones that you will use in your service, the other being used by Service Fabric runtime.

  • Fabric_ApplicationHostIdFabric_ApplicationHostId
  • Fabric_ApplicationHostTypeFabric_ApplicationHostType
  • Fabric_ApplicationIdFabric_ApplicationId
  • Fabric_ApplicationNameFabric_ApplicationName
  • Fabric_CodePackageInstanceIdFabric_CodePackageInstanceId
  • Fabric_CodePackageNameFabric_CodePackageName
  • Fabric_Endpoint_[YourServiceName]TypeEndpointFabric_Endpoint_[YourServiceName]TypeEndpoint
  • Fabric_Folder_App_LogFabric_Folder_App_Log
  • Fabric_Folder_App_TempFabric_Folder_App_Temp
  • Fabric_Folder_App_WorkFabric_Folder_App_Work
  • Fabric_Folder_ApplicationFabric_Folder_Application
  • Fabric_NodeIdFabric_NodeId
  • Fabric_NodeIPOrFQDNFabric_NodeIPOrFQDN
  • Fabric_NodeNameFabric_NodeName
  • Fabric_RuntimeConnectionAddressFabric_RuntimeConnectionAddress
  • Fabric_ServicePackageInstanceIdFabric_ServicePackageInstanceId
  • Fabric_ServicePackageNameFabric_ServicePackageName
  • Fabric_ServicePackageVersionInstanceFabric_ServicePackageVersionInstance
  • FabricPackageFileNameFabricPackageFileName

次のコードは、Service Fabric の環境変数のリストを表示する方法を示しています。The code belows shows how to list the Service Fabric environment variables

   foreach (DictionaryEntry de in Environment.GetEnvironmentVariables())
   {
       if (de.Key.ToString().StartsWith("Fabric"))
       {
           Console.WriteLine(" Environment variable {0} = {1}", de.Key, de.Value);
       }
   }

ローカルの開発用コンピューターで実行する際の、GuestExe.Application というアプリケーションの種類と FrontEndService というサービスの種類の環境変数の例を次に示します。The following are examples of environment variables for an application type called GuestExe.Application with a service type called FrontEndService when run on your local dev machine.

  • Fabric_ApplicationName = fabric:/GuestExe.ApplicationFabric_ApplicationName = fabric:/GuestExe.Application
  • Fabric_CodePackageName = CodeFabric_CodePackageName = Code
  • Fabric_Endpoint_FrontEndServiceTypeEndpoint = 80Fabric_Endpoint_FrontEndServiceTypeEndpoint = 80
  • Fabric_NodeIPOrFQDN = localhostFabric_NodeIPOrFQDN = localhost
  • Fabric_NodeName = _Node_2Fabric_NodeName = _Node_2

アプリケーション パラメーター ファイルApplication parameter files

Service Fabric アプリケーション プロジェクトには、1 つまたは複数のアプリケーション パラメーター ファイルを含めることができます。The Service Fabric application project can include one or more application parameter files. 各ファイルでは、アプリケーション マニフェストで定義されているパラメーターに対して特定の値を定義します。Each of them defines the specific values for the parameters that are defined in the application manifest:

    <!-- ApplicationParameters\Local.xml -->

    <Application Name="fabric:/Application1" xmlns="http://schemas.microsoft.com/2011/01/fabric">
        <Parameters>
            <Parameter Name ="Stateful1_MinReplicaSetSize" Value="3" />
            <Parameter Name="Stateful1_PartitionCount" Value="1" />
            <Parameter Name="Stateful1_TargetReplicaSetSize" Value="3" />
        </Parameters>
    </Application>

既定では、新しいアプリケーションに Local.1Node.xml、Local.5Node.xml、Cloud.xml という名前の 3 つのパラメーター ファイルが含まれています。By default, a new application includes three application parameter files, named Local.1Node.xml, Local.5Node.xml, and Cloud.xml:

ソリューション エクスプローラーのアプリケーション パラメーター ファイル

パラメーター ファイルを作成するには、既存のパラメーター ファイルをコピーし、それに新しい名前を付けるだけです。To create a parameter file, simply copy and paste an existing one and give it a new name.

デプロイ中に環境固有のパラメーターを識別するIdentifying environment-specific parameters during deployment

デプロイメント時には、アプリケーションで適用する適切なパラメーター ファイルを選択する必要があります。At deployment time, you need to choose the appropriate parameter file to apply with your application. この操作は、Visual Studio の [発行] ダイアログ ボックスで、または PowerShell で行うことができます。You can do this through the Publish dialog in Visual Studio or through PowerShell.

Visual Studio からのデプロイDeploy from Visual Studio

Visual Studio でアプリケーションを発行する場合は、使用可能なパラメーター ファイルの一覧から選択することができます。You can choose from the list of available parameter files when you publish your application in Visual Studio.

[発行] ダイアログ ボックスでパラメーター ファイルを選択する

PowerShell からのデプロイDeploy from PowerShell

アプリケーション プロジェクト テンプレートに含まれる Deploy-FabricApplication.ps1 PowerShell スクリプトは、発行プロファイルをパラメーターとして受け入れます。PublishProfile には、アプリケーション パラメーター ファイルへの参照が含まれています。The Deploy-FabricApplication.ps1 PowerShell script included in the application project template accepts a publish profile as a parameter and the PublishProfile contains a reference to the application parameters file.

  ./Deploy-FabricApplication -ApplicationPackagePath <app_package_path> -PublishProfileFile <publishprofile_path>

次のステップNext steps

このトピックで説明した一部の主要概念の詳細については、 Service Fabric の技術概要に関する記事をご覧ください。To learn more about some of the core concepts that are discussed in this topic, see the Service Fabric technical overview. Visual Studio で使用可能なその他のアプリケーション管理機能については、 Visual Studio での Service Fabric アプリケーションの管理に関する記事をご覧ください。For information about other app management capabilities that are available in Visual Studio, see Manage your Service Fabric applications in Visual Studio.