Reliable Services 使用Get started with Reliable Services

Azure Service Fabric アプリケーションには、コードを実行する 1 つ以上のサービスが含まれています。An Azure Service Fabric application contains one or more services that run your code. ここでは、 Reliable Servicesを使用して、ステートレスとステートフルの両方の Service Fabric アプリケーションを作成する方法を説明します。This guide shows you how to create both stateless and stateful Service Fabric applications with Reliable Services.

基本的な概念Basic concepts

Reliable Services の使用を開始するには、いくつかの基本的な概念を理解する必要があります。To get started with Reliable Services, you only need to understand a few basic concepts:

  • サービスの種類: 使用するサービス実装です。Service type: This is your service implementation. StatelessService を拡張する記述したクラスと、そこで使用する他のコードまたは依存関係のほか、名前やバージョン番号によって定義されます。It is defined by the class you write that extends StatelessService and any other code or dependencies used therein, along with a name and a version number.
  • 名前付きサービス インスタンス: サービスを実行するには、サービスの種類の名前付きインスタンスを作成します。これは、クラスの種類のオブジェクト インスタンスを作成するのに似ています。Named service instance: To run your service, you create named instances of your service type, much like you create object instances of a class type. サービス インスタンスの名前は、"fabric:/MyApp/MyService" のように、"fabric:/" スキームを使用した URI の形式になります。A service instance has a name in the form of a URI using the "fabric:/" scheme, such as "fabric:/MyApp/MyService".
  • サービス ホスト: 作成した名前付きサービス インスタンスは、ホスト プロセス内で実行する必要があります。Service host: The named service instances you create need to run inside a host process. サービス ホストは単なる 1 プロセスで、ここでサービスのインスタンスを実行できます。The service host is just a process where instances of your service can run.
  • サービス登録: 登録はすべてを 1 つにまとめます。Service registration: Registration brings everything together. サービス ホストでサービスの種類を Service Fabric ランタイムに登録して、Service Fabric がそのインスタンスを作成して実行できるようにする必要があります。The service type must be registered with the Service Fabric runtime in a service host to allow Service Fabric to create instances of it to run.

ステートレス サービスの作成Create a stateless service

ステートレス サービスは、クラウド アプリケーションで現在基準となっている種類のサービスです。A stateless service is a type of service that is currently the norm in cloud applications. ステートレスと見なされるのは、確実に格納する必要があるデータや高可用性を実現する必要があるデータが、サービス自体には含まれていないためです。It is considered stateless because the service itself does not contain data that needs to be stored reliably or made highly available. ステートレス サービスのインスタンスが終了すると、すべての内部状態が失われます。If an instance of a stateless service shuts down, all of its internal state is lost. この種類のサービスでは、高可用性と高い信頼性を実現するために、Azure テーブルや SQL Database などの外部ストアに状態を格納する必要があります。In this type of service, state must be persisted to an external store, such as Azure Tables or SQL Database, for it to be made highly available and reliable.

Visual Studio 2017 または Visual Studio 2019 を管理者として起動し、HelloWorld という名前の新しい Service Fabric アプリケーション プロジェクトを作成します。Launch Visual Studio 2017 or Visual Studio 2019 as an administrator, and create a new Service Fabric application project named HelloWorld:

[新しいプロジェクト] ダイアログを使用して新しい Service Fabric アプリケーションを作成する

次に、 .NET Core 2.0 を使用して、HelloWorldStateless という名前のステートレス サービス プロジェクトを作成します。Then create a stateless service project using .NET Core 2.0 named HelloWorldStateless:

2 番目のダイアログ ボックスでステートレス サービス プロジェクトを作成する

これで、ソリューションには、次の 2 つのプロジェクトが含まれています。Your solution now contains two projects:

  • HelloWorldHelloWorld. これはサービスを含むアプリケーション プロジェクトです。This is the application project that contains your services. また、アプリケーションを説明するアプリケーション マニフェストと、アプリケーションをデプロイするのに役立つ多くの PowerShell スクリプトも含まれます。It also contains the application manifest that describes the application, as well as a number of PowerShell scripts that help you to deploy your application.
  • HelloWorldStatelessHelloWorldStateless. これはサービス プロジェクトです。This is the service project. ステートレス サービスの実装が含まれています。It contains the stateless service implementation.

サービスの実装Implement the service

サービス プロジェクト内にある HelloWorldStateless.cs ファイルを開きます。Open the HelloWorldStateless.cs file in the service project. Service Fabric では、どのようなビジネス ロジックもサービスで実行できます。In Service Fabric, a service can run any business logic. サービス API には、コードのエントリ ポイントが 2 つあります。The service API provides two entry points for your code:

  • RunAsyncという変更可能なエントリ ポイント メソッドでは、実行時間の長いコンピューティング ワークロードなどの任意のワークロードの実行を開始できます。An open-ended entry point method, called RunAsync, where you can begin executing any workloads, including long-running compute workloads.
protected override async Task RunAsync(CancellationToken cancellationToken)
{
    ...
}
  • 選択した通信スタック (ASP.NET Core など) を接続できる通信エントリ ポイント。A communication entry point where you can plug in your communication stack of choice, such as ASP.NET Core. これは、ユーザーおよびその他のサービスからの要求の受信を開始できる場所です。This is where you can start receiving requests from users and other services.
protected override IEnumerable<ServiceInstanceListener> CreateServiceInstanceListeners()
{
    ...
}

このチュートリアルでは、 RunAsync() エントリ ポイント メソッドを取り上げます。In this tutorial, we will focus on the RunAsync() entry point method. これは、コードの実行をすぐに開始できる場所です。This is where you can immediately start running your code. プロジェクト テンプレートには、ローリング カウントをインクリメントする RunAsync() の実装例が含まれます。The project template includes a sample implementation of RunAsync() that increments a rolling count.

注意

通信スタックを使用する方法の詳細については、ASP.NET Core とのサービス通信に関するページを参照してください。For details about how to work with a communication stack, see Service communication with ASP.NET Core

RunAsyncRunAsync

protected override async Task RunAsync(CancellationToken cancellationToken)
{
    // TODO: Replace the following sample code with your own logic
    //       or remove this RunAsync override if it's not needed in your service.

    long iterations = 0;

    while (true)
    {
        cancellationToken.ThrowIfCancellationRequested();

        ServiceEventSource.Current.ServiceMessage(this.Context, "Working-{0}", ++iterations);

        await Task.Delay(TimeSpan.FromSeconds(1), cancellationToken);
    }
}

プラットフォームは、サービスのインスタンスが配置され実行準備ができたときに、このメソッドを呼び出します。The platform calls this method when an instance of a service is placed and ready to execute. ステートレス サービスの場合、これは単にサービス インスタンスが開いたことを意味します。For a stateless service, that simply means when the service instance is opened. サービス インスタンスを終了する必要がある場合のために、キャンセル トークンが提供されています。A cancellation token is provided to coordinate when your service instance needs to be closed. Service Fabric では、サービス インスタンスの開始から終了のサイクルは、サービスのライフタイムで何度も発生する可能性があります。In Service Fabric, this open/close cycle of a service instance can occur many times over the lifetime of the service as a whole. これは、さまざまな理由で発生する可能性があります。This can happen for various reasons, including:

  • システムがリソース分散のためにサービス インスタンスを移動している。The system moves your service instances for resource balancing.
  • コードでエラーが発生している。Faults occur in your code.
  • アプリケーションまたはシステムがアップグレードされている。The application or system is upgraded.
  • 基礎となるハードウェアで障害が発生している。The underlying hardware experiences an outage.

この調整は、サービスの可用性を高めて適切なバランスを取るために、システムによって管理されます。This orchestration is managed by the system to keep your service highly available and properly balanced.

RunAsync() は同期的なブロックを行いません。RunAsync() should not block synchronously. RunAsync の実装では、タスクを返すか、長時間にわたって実行される操作またはブロック操作を待機して、ランタイムを続行できるようにします。Your implementation of RunAsync should return a Task or await on any long-running or blocking operations to allow the runtime to continue. 前の例の while(true) ループでは、タスクを返す await Task.Delay() が使用されています。Note in the while(true) loop in the previous example, a Task-returning await Task.Delay() is used. ワークロードで同期的にブロックする必要がある場合は、RunAsync 実装で Task.Run() を使用して新しいタスクをスケジュールする必要があります。If your workload must block synchronously, you should schedule a new Task with Task.Run() in your RunAsync implementation.

ワークロードの取り消しは、提供されたキャンセル トークンを使用して協調的に調整されます。Cancellation of your workload is a cooperative effort orchestrated by the provided cancellation token. システムはタスクが完了 (正常に完了、キャンセル、または失敗) するまで待機してから、次に進みます。The system will wait for your task to end (by successful completion, cancellation, or fault) before it moves on. システムからキャンセルが要求された場合は、キャンセル トークンを利用して作業を完了し、できるだけ早く RunAsync() を終了することが重要です。It is important to honor the cancellation token, finish any work, and exit RunAsync() as quickly as possible when the system requests cancellation.

このステートレス サービスの例では、カウントはローカル変数に格納されます。In this stateless service example, the count is stored in a local variable. これはステートレス サービスであるため、保存される値は、サービス インスタンスの現在のライフサイクルのみで保持されます。But because this is a stateless service, the value that's stored exists only for the current lifecycle of its service instance. このサービスを移動または再起動すると、値は失われます。When the service moves or restarts, the value is lost.

ステートフル サービスの作成Create a stateful service

Service Fabric には、新しい種類のステートフルなサービスが導入されています。Service Fabric introduces a new kind of service that is stateful. ステートフル サービスは、サービス内に状態を確実に維持でき、それを使用するコードと同じ場所に配置できます。A stateful service can maintain state reliably within the service itself, co-located with the code that's using it. Service Fabric によって状態の可用性が高まるため、外部ストアに状態を維持する必要がなくなります。State is made highly available by Service Fabric without the need to persist state to an external store.

サービスが移動または再起動した場合でも、カウンター値をステートレスから高可用と永続性に変換するには、ステートフル サービスが必要です。To convert a counter value from stateless to highly available and persistent, even when the service moves or restarts, you need a stateful service.

先ほどと同じ HelloWorld アプリケーションで、アプリケーション プロジェクトの [サービス] を右クリックし、 [追加] -> [新しい Service Fabric サービス] を選択することで、新しいサービスを追加できます。In the same HelloWorld application, you can add a new service by right-clicking on the Services references in the application project and selecting Add -> New Service Fabric Service.

Service Fabric アプリケーションにサービスを追加します。

[.NET Core 2.0]、[ステートフル サービス] の順に選択し、HelloWorldStateful という名前を付けます。Select .NET Core 2.0 -> Stateful Service and name it HelloWorldStateful. [OK] をクリックします。Click OK.

[新しいプロジェクト] ダイアログを使用して新しい Service Fabric のステートフル サービスを作成する

これで、アプリケーションには、ステートレス サービス HelloWorldStateless とステートフル サービス HelloWorldStateful の 2 つのサービスが含まれるようになります。Your application should now have two services: the stateless service HelloWorldStateless and the stateful service HelloWorldStateful.

ステートフル サービスのエントリ ポイントは、ステートレス サービスと同じです。A stateful service has the same entry points as a stateless service. 主な違いは、状態プロバイダーを使用して状態を確実に保存できることです。The main difference is the availability of a state provider that can store state reliably. Service Fabric には、Reliable Collection という状態プロバイダー実装が用意されています。Reliable Collection では、Reliable State Manager を使用してレプリケートされたデータ構造を作成できます。Service Fabric comes with a state provider implementation called Reliable Collections, which lets you create replicated data structures through the Reliable State Manager. ステートフル Reliable Service では、この状態プロバイダーを既定で使用します。A stateful Reliable Service uses this state provider by default.

HelloWorldStateful で、次の RunAsync メソッドを含む HelloWorldStateful.csを開きます。Open HelloWorldStateful.cs in HelloWorldStateful, which contains the following RunAsync method:

protected override async Task RunAsync(CancellationToken cancellationToken)
{
    // TODO: Replace the following sample code with your own logic
    //       or remove this RunAsync override if it's not needed in your service.

    var myDictionary = await this.StateManager.GetOrAddAsync<IReliableDictionary<string, long>>("myDictionary");

    while (true)
    {
        cancellationToken.ThrowIfCancellationRequested();

        using (var tx = this.StateManager.CreateTransaction())
        {
            var result = await myDictionary.TryGetValueAsync(tx, "Counter");

            ServiceEventSource.Current.ServiceMessage(this.Context, "Current Counter Value: {0}",
                result.HasValue ? result.Value.ToString() : "Value does not exist.");

            await myDictionary.AddOrUpdateAsync(tx, "Counter", 0, (key, value) => ++value);

            // If an exception is thrown before calling CommitAsync, the transaction aborts, all changes are
            // discarded, and nothing is saved to the secondary replicas.
            await tx.CommitAsync();
        }

        await Task.Delay(TimeSpan.FromSeconds(1), cancellationToken);
    }

RunAsyncRunAsync

RunAsync() は、ステートフル サービスとステートレス サービスで同様に動作します。RunAsync() operates similarly in stateful and stateless services. ただし、ステートフル サービスでは、プラットフォームは、 RunAsync()を実行する前に、ユーザーに代わって追加の作業を行います。However, in a stateful service, the platform performs additional work on your behalf before it executes RunAsync(). この作業には、Reliable State Manager と Reliable Collection が使用できる状態にあることの確認が含まれる場合があります。This work can include ensuring that the Reliable State Manager and Reliable Collections are ready to use.

Reliable Collection と Reliable State ManagerReliable Collections and the Reliable State Manager

var myDictionary = await this.StateManager.GetOrAddAsync<IReliableDictionary<string, long>>("myDictionary");

IReliableDictionary は、サービスに状態を確実に格納するために使用できるディクショナリ実装です。IReliableDictionary is a dictionary implementation that you can use to reliably store state in the service. Service Fabric と Reliable Collection を使用すると、データをサービスに直接格納できるため、外部の永続ストアが必要ありません。With Service Fabric and Reliable Collections, you can store data directly in your service without the need for an external persistent store. Reliable Collection により、データの可用性が向上します。Reliable Collections make your data highly available. Service Fabric では、サービスの複数の レプリカ を作成して管理することでこれを実現します。Service Fabric accomplishes this by creating and managing multiple replicas of your service for you. また、これらのレプリカとその状態遷移の管理の複雑さを取り除く API も提供します。It also provides an API that abstracts away the complexities of managing those replicas and their state transitions.

Reliable Collection にはカスタム型を含むすべての .NET 型を格納できます。ただし次の点にご注意ください。Reliable Collections can store any .NET type, including your custom types, with a couple of caveats:

  • Service Fabric がノード全体で状態をレプリケートして状態の可用性を高め、Reliable Collection が各レプリカでデータをローカル ディスクに保存します。Service Fabric makes your state highly available by replicating state across nodes, and Reliable Collections store your data to local disk on each replica. これは、Reliable Collection で保存されるすべてのデータはシリアル化可能である必要があることを意味します。This means that everything that is stored in Reliable Collections must be serializable. 既定では、Reliable Collection は DataContract を使用してシリアル化します。そのため、既定のシリアライザーを使用する場合は、使用する型がデータ コントラクト シリアライザーでサポートされていることを確認することが重要です。By default, Reliable Collections use DataContract for serialization, so it's important to make sure that your types are supported by the Data Contract Serializer when you use the default serializer.

  • Reliable Collection でトランザクションをコミットすると、可用性が高めるためにオブジェクトがレプリケートされます。Objects are replicated for high availability when you commit transactions on Reliable Collections. Reliable Collection に格納されるオブジェクトは、サービスのローカル メモリに保持されます。Objects stored in Reliable Collections are kept in local memory in your service. これは、オブジェクトへのローカルな参照があることを意味します。This means that you have a local reference to the object.

    トランザクションの Reliable Collection を更新せずに、これらのオブジェクトのローカル インスタンスを変更しないようにしてください。It is important that you do not mutate local instances of those objects without performing an update operation on the reliable collection in a transaction. オブジェクトのローカル インスタンスの変更は自動的にレプリケートされないためです。This is because changes to local instances of objects will not be replicated automatically. オブジェクトをディクショナリに再挿入するか、ディクショナリで update メソッドのいずれかを使用する必要があります。You must re-insert the object back into the dictionary or use one of the update methods on the dictionary.

Reliable Collection の管理は Reliable State Manager が行います。The Reliable State Manager manages Reliable Collections for you. サービス内のどの場所でも、Reliable Collection の名前を指定することで、Reliable State Manager に Reliable Collection をいつでも要求できます。You can simply ask the Reliable State Manager for a reliable collection by name at any time and at any place in your service. Reliable State Manager により、参照を確実に取得できます。The Reliable State Manager ensures that you get a reference back. Reliable Collection インスタンスへの参照をクラス メンバー変数やプロパティに保存することはお勧めしません。We don't recommended that you save references to reliable collection instances in class member variables or properties. サービスのライフサイクル中、参照が常にインスタンスに設定されていることを保証するために特に注意を払う必要があります。Special care must be taken to ensure that the reference is set to an instance at all times in the service lifecycle. この作業は Reliable State Manager によって処理され、繰り返されるアクセスのために最適化されます。The Reliable State Manager handles this work for you, and it's optimized for repeat visits.

トランザクション処理と非同期処理Transactional and asynchronous operations

using (ITransaction tx = this.StateManager.CreateTransaction())
{
    var result = await myDictionary.TryGetValueAsync(tx, "Counter-1");

    await myDictionary.AddOrUpdateAsync(tx, "Counter-1", 0, (k, v) => ++v);

    await tx.CommitAsync();
}

Reliable Collection には、統合言語クエリ (LINQ) を除き、対応する System.Collections.GenericSystem.Collections.Concurrent が実行する操作と同じ操作が多数あります。Reliable Collections have many of the same operations that their System.Collections.Generic and System.Collections.Concurrent counterparts do, except for Language Integrated Query (LINQ). Reliable Collection での操作は非同期です。Operations on Reliable Collections are asynchronous. Reliable Collection での書き込み操作では、データをレプリケートしてディスクに保持するために I/O 操作が実行されるためです。This is because write operations with Reliable Collections perform I/O operations to replicate and persist data to disk.

Reliable Collection の操作は トランザクションであるため、複数の Reliable Collection と操作で状態の整合性を維持できます。Reliable Collection operations are transactional, so that you can keep state consistent across multiple Reliable Collections and operations. たとえば、1 つのトランザクション内で Reliable Queue から作業項目をデキューし、その項目の操作を実行してから、結果を Reliable Dictionary に保存するとします。For example, you may dequeue a work item from a Reliable Queue, perform an operation on it, and save the result in a Reliable Dictionary, all within a single transaction. これはアトミック操作として扱われので、操作全体が成功するか、操作全体がロールバックされることが保証されます。This is treated as an atomic operation, and it guarantees that either the entire operation will succeed or the entire operation will roll back. 項目をデキューしたが、結果を保存する前にエラーが発生した場合は、トランザクション全体がロールバックされ、項目は処理のためにキューに残ります。If an error occurs after you dequeue the item but before you save the result, the entire transaction is rolled back and the item remains in the queue for processing.

アプリケーションの実行Run the application

HelloWorld アプリケーションに戻ります。We now return to the HelloWorld application. ここからサービスを構築してデプロイできます。You can now build and deploy your services. F5キーを押すと、アプリケーションがビルドされ、ローカル クラスターにデプロイされます。When you press F5, your application will be built and deployed to your local cluster.

サービスが開始されたら、生成された Event Tracing for Windows (ETW) イベントを [診断イベント] ウィンドウで確認できます。After the services start running, you can view the generated Event Tracing for Windows (ETW) events in a Diagnostic Events window. アプリケーションのステートレス サービスとステートフル サービスの両方のイベントが表示されるのでご注意ください。Note that the events displayed are from both the stateless service and the stateful service in the application. [一時停止] ボタンをクリックして、ストリームを一時停止できます。You can pause the stream by clicking the Pause button. その後、メッセージを展開して、メッセージの詳細を調べることができます。You can then examine the details of a message by expanding that message.

注意

アプリケーションを実行する前に、ローカル開発クラスターが実行されていることを確認します。Before you run the application, make sure that you have a local development cluster running. ローカル環境の設定については、 ファースト ステップ ガイド をご覧ください。Check out the getting started guide for information on setting up your local environment.

Visual Studio で診断イベントを表示する

次のステップNext steps

Visual Studio での Service Fabric アプリケーションのデバッグDebug your Service Fabric application in Visual Studio

はじめに: OWIN 自己ホストによる Service Fabric Web API サービスGet started: Service Fabric Web API services with OWIN self-hosting

Reliable Collection の詳細Learn more about Reliable Collections

アプリケーションをデプロイするDeploy an application

アプリケーションのアップグレードApplication upgrade

Reliable Services の開発者向けリファレンスDeveloper reference for Reliable Services