次の方法で共有


.NET Aspire Redis®* 統合

含まれるもの:ホスティング統合Client 統合

Redis は、キャッシュ、ベクター検索、および NoSQL データベースのための世界最速のデータ プラットフォームです。 .NET Aspire Redis 統合を使用すると、既存の Redis インスタンスに接続したり、docker.io/library/redis コンテナー イメージを使用して .NET から新しいインスタンスを作成したりできます。

Garnet は、Microsoft Research のハイ パフォーマンス キャッシュ ストアであり、Redis シリアル化プロトコル (RESP) に準拠しています。 .NET Aspire Redis 統合を使用すると、既存の Garnet インスタンスに接続したり、ghcr.io/microsoft/garnet コンテナー イメージを使用して .NET から新しいインスタンスを作成したりできます。

Valkey は Redis フォークであり、Redis シリアル化プロトコル (RESP) に準拠しています。 キャッシュ、メッセージ キューなど、さまざまなワークロードをサポートし、プライマリ データベースとして機能できる、高パフォーマンスのキー/値データストアです。 .NET Aspire Redis 統合を使用すると、既存の Valkey インスタンスに接続したり、docker.io/valkey/valkey コンテナー イメージを使用して .NET から新しいインスタンスを作成したりできます。

ホスティング統合

Redis ホスティング統合は、RedisResource の種類として Redis リソースをモデル化します。 この型とその API にアクセスして、📦Aspireに追加できるようにするには、アプリホスト プロジェクトで NuGet パッケージをRedis ホスティングします。

dotnet add package Aspire.Hosting.Redis

詳細については、「dotnet パッケージ の追加」または「.NET アプリケーションでのパッケージの依存関係の管理」を参照してください。

Redisリソースを追加する

アプリ ホスト プロジェクトで、builder インスタンスの AddRedis を呼び出して、Redis リソースを追加します。

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

.NET .NET Aspire 前の例で示したように、docker.io/Redis/Redis イメージでコンテナー イメージをアプリ ホストに追加すると、ローカル コンピューターに新しい Redis インスタンスが作成されます。 Redis リソース (cache 変数) への参照が ExampleProjectに追加されます。

WithReference メソッドは、"cache"という名前の ExampleProject で接続を構成します。 詳細については、「コンテナー リソースのライフサイクルの」を参照してください。

ヒント

既存の Redis インスタンスに接続する場合は、代わりに AddConnectionString 呼び出します。 詳細については、「既存のリソースを参照する」を参照してください。

Redis Insights を使用してリソース Redis 追加する

Redis Insights を Redis リソースに追加するには、WithRedisInsight メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithRedisInsight();

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

Redis Insights は、AI アシスタントである Copilot Redis の助けを借りて、すべてのオペレーティング システムと Redis デプロイの Redis データを分析するための無料のグラフィカル インターフェイスです。 .NET .NET Aspire は、コマンダー アプリを実行する別のコンテナー イメージ docker.io/redis/redisinsight をアプリ ホストに追加します。

手記

RedisInsightResource のホスト ポートを構成するには、WithHostPort API への呼び出しをチェーンし、目的のポート番号を指定します。

Redis リソースを Redis コマンダーで追加する

Redis リソースに Redis Commander を追加するには、WithRedisCommander メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithRedisCommander();

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

Redis Commander は、Redis データベースの表示、編集、管理に使用される Node.js Web アプリケーションです。 .NET .NET Aspire は、コマンダー アプリを実行する別のコンテナー イメージ docker.io/rediscommander/redis-commander をアプリ ホストに追加します。

ヒント

RedisCommanderResource のホスト ポートを構成するには、WithHostPort API への呼び出しをチェーンし、目的のポート番号を指定します。

データボリュームを持つ Redis リソースを追加する

Redis リソースにデータ ボリュームを追加するには、Redis リソースで WithDataVolume メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithDataVolume(isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

データ ボリュームは、Redis データをコンテナーのライフサイクル外に保持するために使用されます。 データ ボリュームは、Redis コンテナー内の /data パスにマウントされ、name パラメーターが指定されていない場合、名前はランダムに生成されます。 データ ボリュームの詳細と、マウントのバインド 優先される理由の詳細については、「 ドキュメント: ボリューム」を参照してください。

データ バインドマウントによる Redis リソースを追加する

Redis リソースにデータ バインド マウントを追加するには、WithDataBindMount メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithDataBindMount(
                       source: @"C:\Redis\Data",
                       isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

大事な

データ バインド マウント、パフォーマンス、移植性、およびセキュリティが向上し、運用環境に適した ボリュームと比較して機能が制限されています。 ただし、バインド マウントを使用すると、ホスト システム上のファイルに直接アクセスして変更できるため、リアルタイムの変更が必要な開発とテストに最適です。

データ バインド マウントは、ホスト マシンのファイルシステムに依存して、コンテナーの再起動間に Redis データを保持します。 データ バインド マウントは、Redis コンテナー内のホスト コンピューター上の Windows 上の C:\Redis\Data (または Unixの /Redis/Data) パスにマウントされます。 データ バインド マウントの詳細については、「Docker のドキュメント: バインドマウント」を参照してください。

持続的にRedisリソースを追加する

Redis リソースに永続化を追加するには、データ ボリュームまたはデータ バインド マウントを使用して WithPersistence メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithDataVolume()
                   .WithPersistence(
                       interval: TimeSpan.FromMinutes(5),
                       keysChangedThreshold: 100);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

上記のコードでは、指定した間隔としきい値で Redis データのスナップショットを取得することで、Redis リソースに永続化を追加します。 interval はスナップショットのエクスポートから keysChangedThreshold までの時間であり、スナップショットのトリガーに必要なキー変更操作の数です。 永続化の詳細については、「Redis ドキュメント: 永続化の」を参照してください。

Garnet ホスティング統合では、Garnet リソースが GarnetResource の種類としてモデル化されます。 この型と、📦Aspireに追加できる API にアクセスするには、Hosting.Garnet NuGet パッケージを アプリ ホスト プロジェクトに含めます。

dotnet add package Aspire.Hosting.Garnet

詳細については、「dotnet パッケージ の追加」または「.NET アプリケーションでのパッケージの依存関係の管理」を参照してください。

Garnet リソースの追加

アプリ ホスト プロジェクトで、builder インスタンスの AddGarnet を呼び出して、Garnet リソースを追加します。

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddGarnet("cache");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

.NET .NET Aspire 前の例で示したように、ghcr.io/microsoft/garnet イメージを使用してコンテナー イメージをアプリ ホストに追加すると、ローカル コンピューターに新しい Garnet インスタンスが作成されます。 Garnet リソース (cache 変数) への参照が ExampleProjectに追加されます。

WithReference メソッドは、"cache"という名前の ExampleProject で接続を構成します。 詳細については、「コンテナー リソースのライフサイクルの」を参照してください。

ヒント

既存の Garnet インスタンスに接続する場合は、代わりに AddConnectionString 呼び出します。 詳細については、「既存のリソースを参照する」を参照してください。

データ ボリュームを使用して Garnet リソースを追加する

Garnet リソースにデータ ボリュームを追加するには、Garnet リソースで AddGarnet メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddGarnet("cache")
                   .WithDataVolume(isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

データ ボリュームは、コンテナーのライフサイクル外に Garnet データを保持するために使用されます。 データ ボリュームは Garnet コンテナーの /data パスにマウントされ、name パラメーターが指定されていない場合、名前はランダムに生成されます。 データボリュームやそれがマウントのバインド よりも好まれる理由の詳細については、「ボリュームに関する ドキュメント」を参照してください。

データ バインド マウントを使用して Garnet リソースを追加する

Garnet リソースにデータ バインド マウントを追加するには、WithDataBindMount メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddGarnet("cache")
                   .WithDataBindMount(
                       source: @"C:\Garnet\Data",
                       isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

重要

データ バインド マウント、パフォーマンス、移植性、およびセキュリティが向上し、運用環境に適した ボリュームと比較して機能が制限されています。 ただし、バインド マウントを使用すると、ホスト システム上のファイルに直接アクセスして変更できるため、リアルタイムの変更が必要な開発とテストに最適です。

データ バインド マウントは、コンテナーの再起動の間に Garnet データを保持するために、ホスト マシンのファイルシステムに依存します。 データ バインド マウントは、Garnet コンテナー内のホスト コンピューター上の Windows 上の C:\Garnet\Data (または Unixの /Garnet/Data) パスにマウントされます。 データ バインド マウントの詳細については、「Docker ドキュメント: バインドマウント」を参照してください。

永続化を使用して Garnet リソースを追加する

Garnet リソースに永続化を追加するには、データ ボリュームまたはデータ バインド マウントを使用して WithPersistence メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddGarnet("cache")
                   .WithDataVolume()
                   .WithPersistence(
                       interval: TimeSpan.FromMinutes(5),
                       keysChangedThreshold: 100);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

上記のコードでは、指定された間隔としきい値で Garnet データのスナップショットを取得することで、Redis リソースに永続化を追加します。 interval はスナップショットのエクスポートから keysChangedThreshold までの時間であり、スナップショットのトリガーに必要なキー変更操作の数です。 永続化の詳細については、「Redis ドキュメント: 永続化の」を参照してください。

Valkey ホスティング統合では、Valkey リソースが ValkeyResource の種類としてモデル化されます。 この型と、📦Aspireに追加できる API にアクセスするには、Hosting.Valkeyアプリ ホスト プロジェクト内の NuGet パッケージ。

dotnet add package Aspire.Hosting.Valkey

詳細については、「dotnet パッケージ の追加」または「.NET アプリケーションでのパッケージの依存関係の管理」を参照してください。

Valkey リソースの追加

アプリ ホスト プロジェクトで、builder インスタンスの AddValkey を呼び出して Valkey リソースを追加します。

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddValkey("cache");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

.NET .NET Aspire 前の例で示したように、docker.io/valkey/valkey イメージを使用してコンテナー イメージをアプリ ホストに追加すると、ローカル コンピューターに新しい Valkey インスタンスが作成されます。 Valkey リソース (cache 変数) への参照が ExampleProjectに追加されます。

WithReference メソッドは、"cache"という名前の ExampleProject で接続を構成します。 詳細については、「コンテナー リソースのライフサイクルの」を参照してください。

助言

既存の Valkey インスタンスに接続する場合は、代わりに AddConnectionString を呼び出します。 詳細については、「既存のリソースを参照する」を参照してください。

データ ボリュームを使用して Valkey リソースを追加する

Valkey リソースにデータ ボリュームを追加するには、Valkey リソースで AddValkey メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddValkey("cache")
                   .WithDataVolume(isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

データ ボリュームは、コンテナーのライフサイクル外に Valkey データを保持するために使用されます。 データ ボリュームは Valkey コンテナーの /data パスにマウントされ、name パラメーターが指定されていない場合、名前はランダムに生成されます。 データ ボリュームの詳細と、マウントのバインド 優先される理由の詳細については、「 ドキュメント: ボリューム」を参照してください。

データ バインド マウントを使用して Valkey リソースを追加する

Valkey リソースにデータ バインド マウントを追加するには、WithDataBindMount メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddValkey("cache")
                   .WithDataBindMount(
                       source: @"C:\Valkey\Data",
                       isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

大事な

データ バインド マウント、パフォーマンス、移植性、およびセキュリティが向上し、運用環境に適した ボリュームと比較して機能が制限されています。 ただし、バインド マウントを使用すると、ホスト システム上のファイルに直接アクセスして変更できるため、リアルタイムの変更が必要な開発とテストに最適です。

データ バインド マウントは、コンテナーの再起動の間に Valkey データを保持するために、ホスト マシンのファイルシステムに依存します。 データ バインド マウントは、Valkey コンテナー内のホスト コンピューター上の Windows 上の C:\Valkey\Data (または Unix上の /Valkey/Data) パスにマウントされます。 データ バインド マウントの詳細については、「Docker ドキュメント: バインド マウント」を参照してください。

Valkey リソースを永続化を用いて追加せよ

Valkey リソースに永続化を追加するには、データ ボリュームまたはデータ バインド マウントを使用して WithPersistence メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddValkey("cache")
                   .WithDataVolume()
                   .WithPersistence(
                       interval: TimeSpan.FromMinutes(5),
                       keysChangedThreshold: 100);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(cache);

// After adding all resources, run the app...

上記のコードでは、指定した間隔としきい値で Valkey データのスナップショットを取得することで、Redis リソースに永続化を追加します。 interval はスナップショットのエクスポートから keysChangedThreshold までの時間であり、スナップショットのトリガーに必要なキー変更操作の数です。 永続化の詳細については、「Redis ドキュメント: 永続化の」を参照してください。

ホスティング統合の正常性チェック

Redis ホスティング統合により、適切なリソースの種類の正常性チェックが自動的に追加されます。 正常性チェックでは、server が実行されていることと、その server への接続を確立できることを確認します。

ホスティング統合は、 AspNetCore.HealthChecks NuGet パッケージに依存します。

Client 統合

.NET Aspire Stack Exchange Redisclient 統合を開始するには、clientを消費するプロジェクト、つまり、Redisclientを使用するアプリケーションのプロジェクトに、📦AspireNuGet パッケージをインストールします。これが完了したら、Redis を行います。 Redis client 統合は、Redisとの対話に使用できる IConnectionMultiplexer インスタンスを登録します。

dotnet add package Aspire.StackExchange.Redis

Redis client の追加

client-consuming プロジェクトの Program.cs ファイルで、任意の IHostApplicationBuilderAddRedisClient 拡張メソッドを呼び出して、依存関係挿入コンテナー経由で使用する IConnectionMultiplexer を登録します。 このメソッドは、接続名パラメーターを受け取ります。

builder.AddRedisClient(connectionName: "cache");

ヒント

connectionName パラメーターは、アプリ ホスト プロジェクトに Redis リソースを追加するときに使用する名前と一致する必要があります。 詳細については、「Redis リソースを追加」を参照してください。

- For the gratuity meaning: チップ - For the advice/hint meaning: ヒント

connectionName パラメーターは、アプリ ホスト プロジェクトで Garnet リソースを追加するときに使用する名前と一致する必要があります。 詳細については、「Garnet リソースの追加」を参照してください。

ヒント

connectionName パラメーターは、アプリ ホスト プロジェクトで Valkey リソースを追加するときに使用する名前と一致する必要があります。 詳細については、「Valkey リソースの追加」を参照してください。

その後、依存関係の挿入を使用して IConnection インスタンスを取得できます。 たとえば、サービスの例から接続を取得するには、次のようにします。

public class ExampleService(IConnectionMultiplexer connectionMux)
{
    // Use connection multiplexer...
}

依存関係の挿入の詳細については、.NET 依存関係の挿入を参照してください。

キー付き Redisclient を追加する

接続名が異なる複数の IConnectionMultiplexer インスタンスを登録する場合があります。 キー付き Redis クライアントを登録するには、AddKeyedRedisClient メソッドを呼び出します。

builder.AddKeyedRedisClient(name: "chat");
builder.AddKeyedRedisClient(name: "queue");

その後、依存関係の挿入を使用して IConnectionMultiplexer インスタンスを取得できます。 たとえば、サービスの例から接続を取得するには、次のようにします。

public class ExampleService(
    [FromKeyedServices("chat")] IConnectionMultiplexer chatConnectionMux,
    [FromKeyedServices("queue")] IConnectionMultiplexer queueConnectionMux)
{
    // Use connections...
}

キー付きサービスの詳細については、「.NET 依存関係の挿入: キー付きサービスの」を参照してください。

構成

.NET Aspire Stack Exchange Redisclient 統合には、プロジェクトの要件と規則に基づいて Redis 接続を構成するための複数のオプションが用意されています。

接続文字列を使用する

ConnectionStrings 構成セクションの接続文字列を使用する場合は、AddRedisを呼び出すときに接続文字列の名前を指定できます。

builder.AddRedis("cache");

ConnectionStrings 構成セクションの接続文字列を使用する場合は、AddGarnetを呼び出すときに接続文字列の名前を指定できます。

builder.AddGarnet("cache");

ConnectionStrings 構成セクションの接続文字列を使用する場合は、AddValkeyを呼び出すときに接続文字列の名前を指定できます。

builder.AddValkey("cache");

その後、接続文字列は ConnectionStrings 構成セクションから取得されます。

{
  "ConnectionStrings": {
    "cache": "localhost:6379"
  }
}

この接続文字列の書式を設定する方法の詳細については、Stack Exchange Redis 構成ドキュメントを参照してください。

構成プロバイダーを使用する

.NET Aspire Stack Exchange Redis 統合では、Microsoft.Extensions.Configurationがサポートされます。 Aspire:StackExchange:Redis キーを使用して、構成から StackExchangeRedisSettings を読み込みます。 いくつかのオプションを構成する appsettings.json の例:

{
  "Aspire": {
    "StackExchange": {
      "Redis": {
        "ConnectionString": "localhost:6379",
        "DisableHealthChecks": true,
        "DisableTracing": false
      }
    }
  }
}

完全な Redisclient 統合 JSON スキーマについては、Aspireを参照してください。RedisStackExchange/ConfigurationSchemajson.

インライン デリゲートを使用する

Action<StackExchangeRedisSettings> デリゲートを渡して、一部またはすべてのオプションをインラインで設定することもできます。たとえば、DisableTracingを構成します。

builder.AddRedisClient(
    "cache",
    static settings => settings.DisableTracing = true);

Client の統合ヘルスチェック

既定では、.NET.NET Aspire 統合により、すべてのサービス 正常性チェック が有効になります。 詳細については、.NET.NET Aspire 統合の概要を参照してください。

.NET Aspire Stack Exchange Redis 統合では、次の処理が行われます。

  • StackExchangeRedisSettings.DisableHealthChecksfalseされたときに正常性チェックを追加します。これは、コンテナー インスタンスへの接続を試みます。
  • /health HTTP エンドポイントと統合されます。このエンドポイントは、アプリがトラフィックを受け入れる準備ができていると見なされるために、登録されているすべての正常性チェックに合格する必要があります。

可観測性とテレメトリ

統合により、ログ記録、トレース、メトリックの構成が自動的に設定されます。これは、監視の柱 とも呼ばれます。 統合の可観測性とテレメトリの詳細については、統合の概要 参照してください。 バッキング サービスによっては、一部の統合でこれらの機能の一部のみがサポートされる場合があります。 たとえば、一部の統合ではログ記録とトレースがサポートされますが、メトリックはサポートされません。 テレメトリ機能は、「構成」セクションに記載されている手法を使用して無効にすることもできます。

伐採

.NET Aspire Stack Exchange Redis 統合では、次のログ カテゴリが使用されます。

  • Aspire.StackExchange.Redis

トレーシング

.NET Aspire Stack Exchange Redis 統合では、OpenTelemetryを使用して次のトレース アクティビティが出力されます。

  • OpenTelemetry.Instrumentation.StackExchangeRedis

メトリック

.NET Aspire Stack Exchange Redis 統合では、現在、StackExchange.Redis ライブラリの制限により、メトリックが既定でサポートされていません。

ホスティングの統合 AzureRedis

Redis リソースを Azureにデプロイするには、📦Aspire.Hosting.Azure.Redis NuGet パッケージをインストールします。

dotnet add package Aspire.Hosting.Azure.Redis

リソース Azure Cache for Redisserver 追加する

.NET Aspire ホスティング AzureRedis パッケージをインストールしたら、アプリ ホスト プロジェクトで AddAzureRedis 拡張メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddAzureRedis("azcache")

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(cache);

上記の AddAzureRedis の呼び出しでは、Redisserver リソースを Azure Cache for Redisとしてデプロイするように構成します。

大事な

既定では、AddAzureRedis の Microsoft Entra ID 認証を構成します。 これには、client 統合など、これらのリソースに接続する必要があるアプリケーションを変更する必要があります。

Azure Cache for Redis client の追加

既定では、Redis ホスティング統合で AddAzureRedis を呼び出すと、Microsoft の 📦 を構成します。Azure.StackExchangeRedis NuGet パッケージを使用して認証を有効にします。

dotnet add package Microsoft.Azure.StackExchangeRedis

Redis 接続は、client 統合と Microsoft.Azure.StackExchangeRedisを利用して使用できます。 次の構成コードについて考えてみましょう。

var azureOptionsProvider = new AzureOptionsProvider();

var configurationOptions = ConfigurationOptions.Parse(
    builder.Configuration.GetConnectionString("cache") ?? 
    throw new InvalidOperationException("Could not find a 'cache' connection string."));

if (configurationOptions.EndPoints.Any(azureOptionsProvider.IsMatch))
{
    await configurationOptions.ConfigureForAzureWithTokenCredentialAsync(
        new DefaultAzureCredential());
}

builder.AddRedisClient("cache", configureOptions: options =>
{
    options.Defaults = configurationOptions.Defaults;
});

詳細については、Microsoft を参照し、Azure.StackExchangeRedis リポジトリを確認してください。

関連項目

*: Redis は Redis 株式会社の登録商標です。その中のいかなる権利も、Redis 株式会社に留保されます。Microsoft による使用は参照のみを目的としており、Redis と Microsoft の間のスポンサーシップ、保証、所属を示すものではありません。トップに戻りますか?