Partager via

® intégration de la mise en cache distribuée .NET AspireRedis*

  • Article

inclut : intégration d’hébergement et intégration Client

Découvrez comment utiliser l’intégration de mise en cache distribuée .NET AspireRedis. La bibliothèque Aspire.StackExchange.Redis.DistributedCaching est utilisée pour enregistrer un fournisseur IDistributedCache, soutenu par un serveur Redis, avec l’image conteneur docker.io/library/redis.

Découvrez comment utiliser l’intégration de mise en cache distribuée .NET AspireRedis. La bibliothèque Aspire.StackExchange.Redis.DistributedCaching est utilisée pour enregistrer un fournisseur IDistributedCache soutenu par un serveur Garnet avec l’image conteneur ghcr.io/microsoft/garnet.

Découvrez comment utiliser l’intégration de mise en cache distribuée .NET AspireRedis. La bibliothèque Aspire.StackExchange.Redis.DistributedCaching est utilisée pour enregistrer un fournisseur IDistributedCache soutenu par un serveur Valkey avec l’image de conteneur docker.io/valkey/valkey.

Intégration de l’hébergement

L'intégration d'hébergement Redis modélise une ressource Redis en tant que type RedisResource. Pour accéder à ce type et à ces API pour les exprimer sous forme de ressources dans votre projet d'hébergement d'applications , ajoutez le package NuGet 📦Aspire.Hosting.Redis :

dotnet add package Aspire.Hosting.Redis

Pour plus d’informations, consultez dotnet add package ou Gérer les dépendances de paquet dans les applications .NET.

Ajouter Redis ressource

Dans votre projet hôte d’application, appelez AddRedis sur l’instance de builder pour ajouter une ressource Redis :

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Lorsque .NET.NET Aspire ajoute une image conteneur à l’hôte de l’application, comme illustré dans l’exemple précédent avec l’image docker.io/Redis/Redis, il crée une instance de Redis sur votre ordinateur local. Une référence à votre ressource Redis (la variable cache) est ajoutée au ExampleProject.

La méthode WithReference configure une connexion dans le ExampleProject nommé "cache". Pour plus d’informations, consultez le cycle de vie des ressources des conteneurs .

Pourboire

Si vous préférez vous connecter à une instance de Redis existante, appelez AddConnectionString à la place. Pour plus d’informations, consultez Référencer les ressources existantes.

Ajouter la ressource Redis avec Redis Insights

Pour ajouter Redis Insights à la ressource Redis, appelez la méthode 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 est une interface graphique gratuite permettant d’analyser Redis données sur tous les systèmes d’exploitation et les déploiements Redis avec l’aide de notre assistant IA, Redis Copilot. .NET .NET Aspire ajoute une autre image conteneur docker.io/redis/redisinsight sur l'hôte de l'application qui exécute l'application de commande.

Note

Pour configurer le port hôte de la chaîne RedisInsightResource un appel à l’API WithHostPort et fournir le numéro de port souhaité.

Ajouter Redis ressource avec Redis Commander

Pour ajouter le commandant Redis à la ressource Redis, appelez la méthode 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 est une application web Node.js utilisée pour afficher, modifier et gérer une base de données Redis. .NET .NET Aspire ajoute une autre image conteneur docker.io/rediscommander/redis-commander sur l'hôte de l'application qui exécute l'application de commande.

Pourboire

Pour configurer le port hôte de la chaîne RedisCommanderResource un appel à l’API WithHostPort et fournir le numéro de port souhaité.

Ajouter la ressource Redis avec un volume de données

Pour ajouter un volume de données à la ressource Redis, appelez la méthode WithDataVolume sur la ressource Redis :

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...

Le volume de données est utilisé pour conserver les données Redis en dehors du cycle de vie de son conteneur. Le volume de données est monté sur le chemin /data dans le conteneur Redis et lorsqu’un paramètre name n’est pas fourni, le nom est généré aléatoirement. Pour plus d'informations sur les volumes de données et sur la raison pour laquelle ils sont préférés aux montages par liaison , consultez la documentation Docker : Volumes.

Ajouter la ressource Redis avec un montage avec liaison de données

Pour ajouter un montage de liaison de données à la ressource Redis, appelez la méthode 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...

Important

Les montages de liaison de données ont des fonctionnalités limitées par rapport aux volumes, qui offrent une meilleure performance, une meilleure portabilité et une meilleure sécurité, ce qui les rend plus adaptés aux environnements de production. Toutefois, les montages de liaison autorisent l’accès direct et les modifications des fichiers sur le système hôte, idéal pour le développement et les tests nécessitant des modifications en temps réel.

Les montages de liaison de données s’appuient sur le système de fichiers de la machine hôte pour conserver les données Redis lors des redémarrages des conteneurs. Le montage de liaison de données est monté sur le chemin d’accès C:\Redis\Data sur Windows (ou /Redis/Data sur Unix) sur l’ordinateur hôte dans le conteneur Redis. Pour plus d’informations sur les montages de liaison de données, consultez les documents Docker : montages de liaison.

Ajouter la ressource Redis avec persistance

Pour ajouter la persistance à la ressource Redis, appelez la méthode WithPersistence avec le volume de données ou le montage de liaison de données :

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...

Le code précédent ajoute la persistance à la ressource Redis en prenant des instantanés des données Redis à un intervalle et un seuil spécifiés. Le interval est le temps entre les exportations d’instantanés et l'keysChangedThreshold correspond au nombre d’opérations de modification clés requises pour déclencher un instantané. Pour plus d’informations sur la persistance, consultez Redis docs : Persistance.

L'intégration d'hébergement de Garnet modélise une ressource Garnet comme le type de GarnetResource. Pour accéder à ce type et aux API qui vous permettent de l’ajouter à votre package NuGet 📦Aspire.Hosting.Garnet dans le projet hôte de l'application .

dotnet add package Aspire.Hosting.Garnet

Pour plus d’informations, consultez dotnet add package ou Gérer les dépendances de paquet dans les applications .NET.

Ajouter une ressource garnet

Dans votre projet hôte d’application, appelez AddGarnet sur l’instance de builder pour ajouter une ressource Garnet :

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Lorsque .NET.NET Aspire ajoute une image conteneur à l’hôte de l’application, comme illustré dans l’exemple précédent avec l’image ghcr.io/microsoft/garnet, il crée une instance garnet sur votre ordinateur local. Une référence à votre ressource Garnet (la variable cache) est ajoutée au ExampleProject.

La méthode WithReference configure une connexion dans le ExampleProject nommé "cache". Pour plus d’informations, consultez le cycle de vie des ressources des conteneurs .

Pourboire

Si vous préférez vous connecter à une instance garnet existante, appelez AddConnectionString à la place. Pour plus d’informations, consultez Référencer les ressources existantes.

Ajouter une ressource Garnet avec un volume de données

Pour ajouter un volume de données à la ressource Garnet, appelez la méthode AddGarnet sur la ressource Garnet :

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...

Le volume de données est utilisé pour conserver les données garnet en dehors du cycle de vie de son conteneur. Le volume de données est monté sur le chemin d’accès /data dans le conteneur Garnet et lorsqu’un paramètre name n’est pas fourni, le nom est généré au hasard. Pour plus d’informations sur les volumes de données et sur la raison pour laquelle ils sont préférés aux montages de liaison , consultez la documentation Docker : Volumes.

Ajouter une ressource Garnet avec montage de liaison de données

Pour ajouter un montage de liaison de données à la ressource Garnet, appelez la méthode 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...

Important

Les montages de liaison de données ont des fonctionnalités limitées par rapport aux volumes, qui offrent de meilleures performances, la portabilité et la sécurité, ce qui les rend plus adaptés aux environnements de production. Toutefois, les montages de liaison permettent un accès direct et une modification des fichiers sur le système hôte, ce qui est idéal pour le développement et les tests nécessitant des changements en temps réel.

Les montages de liaison de données s'appuient sur le système de fichiers de l'ordinateur hôte pour conserver les données Garnet entre les redémarrages de conteneurs. Le montage bind des données est monté sur le chemin C:\Garnet\Data sous Windows (ou /Garnet/Data sur Unix) sur la machine hôte dans le conteneur Garnet. Pour plus d’informations sur les montages de liaison de données, consultez les documents Docker : montages de liaison.

Ajouter une ressource Garnet avec persistance

Pour ajouter la persistance à la ressource Garnet, appelez la méthode WithPersistence avec le volume de données ou le montage par liaison de données :

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...

Le code précédent ajoute la persistance à la ressource Redis en prenant des captures instantanées des données garnet à un intervalle et un seuil spécifiés. Le interval est le temps entre les exportations d’instantanés et l'keysChangedThreshold correspond au nombre d’opérations de modification clés requises pour déclencher un instantané. Pour plus d’informations sur la persistance, consultez Redis docs : Persistance.

L’hébergement Valkey modélise une ressource Valkey comme type ValkeyResource. Pour accéder à ce type et aux API qui vous permettent de l’ajouter à votre package NuGet 📦Aspire.Hosting.Valkey dans le projet hôte de l'application .

dotnet add package Aspire.Hosting.Valkey

Pour plus d’informations, consultez dotnet add package ou Gérer les dépendances de paquet dans les applications .NET.

Ajouter une ressource Valkey

Dans votre projet hôte d’application, appelez AddValkey sur l’instance de builder pour ajouter une ressource Valkey :

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Lorsque .NET.NET Aspire ajoute une image conteneur à l’hôte de l’application, comme illustré dans l’exemple précédent avec l’image docker.io/valkey/valkey, il crée une instance Valkey sur votre ordinateur local. Une référence à votre ressource Valkey (la variable cache) est ajoutée au ExampleProject.

La méthode WithReference configure une connexion dans le ExampleProject nommé "cache". Pour plus d’informations, consultez le cycle de vie des ressources des conteneurs .

Pourboire

Si vous préférez vous connecter à une instance Valkey existante, appelez AddConnectionString à la place. Pour plus d’informations, consultez Référencer les ressources existantes.

Ajouter une ressource Valkey avec un volume de données

Pour ajouter un volume de données à la ressource Valkey, appelez la méthode AddValkey sur la ressource Valkey :

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...

Le volume de données est utilisé pour conserver les données Valkey en dehors du cycle de vie de son conteneur. Le volume de données est monté sur le chemin /data dans le conteneur Valkey et lorsqu’un paramètre name n’est pas fourni, le nom est généré au hasard. Pour plus d'informations sur les volumes de données et pourquoi ils sont préférés aux montages par liaison, consultez la documentation Docker : Volumes.

Ajouter une ressource Valkey avec montage de liaison de données

Pour ajouter un montage de liaison de données à la ressource Valkey, appelez la méthode 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...

Important

Les montages de liaison de données ont des fonctionnalités limitées par rapport aux volumes, qui offrent de meilleures performances, portabilité et sécurité, les rendant plus adaptés aux environnements de production. Toutefois, les montages de liaison permettent l’accès direct et la modification des fichiers sur le système hôte, ce qui est idéal pour le développement et les tests nécessitant des modifications en temps réel.

Les montages de liaison de données s’appuient sur le système de fichiers de l’ordinateur hôte pour conserver les données Valkey lors des redémarrages des conteneurs. Le montage de liaison de données est effectué sur le chemin d'accès C:\Valkey\Data sur Windows (ou /Valkey/Data sur Unix) sur l'ordinateur hôte dans le conteneur Valkey. Pour plus d’informations sur les montages de liaison de données, consultez les documents Docker : montages de liaison.

Ajouter une ressource Valkey avec persistance

Pour ajouter la persistance à la ressource Valkey, appelez la méthode WithPersistence avec le volume de données ou le point de montage de données :

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...

Le code précédent ajoute la persistance à la ressource Redis en prenant des captures instantanées des données Valkey à un intervalle et un seuil spécifiés. Le interval est le temps entre les exportations d’instantanés et l'keysChangedThreshold correspond au nombre d’opérations de modification clés requises pour déclencher un instantané. Pour plus d’informations sur la persistance, consultez Redis docs : Persistance.

Vérifications d’intégrité de l’intégration d’hébergement

L’intégration d’hébergement Redis ajoute automatiquement un contrôle d’intégrité pour le type de ressource approprié. Le contrôle d’intégrité vérifie que le serveur est en cours d’exécution et qu’une connexion peut être établie à celui-ci.

L'intégration de l'hébergement s'appuie sur les AspNetCore.HealthChecks 📦 et le paquet NuGetRedis.

intégration Client

Pour commencer à utiliser l’intégration de mise en cache distribuée .NET AspireRedis, installez le 📦Aspire. StackExchange.Redis. DistributedCaching package NuGet dans le projet consommant le client, c’est-à-dire le projet pour l’application qui utilise le client de mise en cache distribué Redis. L’intégration du client Redis inscrit une instance de IDistributedCache que vous pouvez utiliser pour interagir avec Redis.

dotnet add package Aspire.StackExchange.Redis.DistributedCaching

Ajouter Redis client

Dans le fichier Program.cs de votre projet consommant le client, appelez l’extension AddRedisDistributedCache pour inscrire les services requis pour la mise en cache distribuée et ajouter un IDistributedCache à utiliser via le conteneur d’injection de dépendances.

builder.AddRedisDistributedCache(connectionName: "cache");

Pourboire

Le paramètre connectionName doit correspondre au nom utilisé lors de l’ajout de la ressource Redis dans le projet hôte de l’application. Pour plus d’informations, consultez Ajouter Redis ressource.

Pourboire

Le paramètre connectionName doit correspondre au nom utilisé lors de l’ajout de la ressource Garnet dans le projet hôte de l’application. Pour plus d’informations, consultez Ajouter une ressource Garnet.

Pourboire

Le paramètre connectionName doit correspondre au nom utilisé lors de l’ajout de la ressource Valkey dans le projet hôte de l’application. Pour plus d’informations, consultez Ajouter une ressource Valkey.

Vous pouvez ensuite récupérer l’instance IDistributedCache à l’aide de l’injection de dépendances. Par exemple, pour récupérer le cache à partir d’un service :

public class ExampleService(IDistributedCache cache)
{
    // Use cache...
}

Pour plus d’informations sur l’injection de dépendances, consultez .NET injection de dépendances.

Ajouter un client clé Redis

Il peut arriver que vous souhaitiez inscrire plusieurs instances de IDistributedCache avec différents noms de connexion. Pour enregistrer des clients Redis, utilisez la méthode AddKeyedRedisDistributedCache :

builder.AddKeyedRedisDistributedCache(name: "chat");
builder.AddKeyedRedisDistributedCache(name: "product");

Vous pouvez ensuite récupérer les instances IDistributedCache à l’aide de l’injection de dépendances. Par exemple, pour récupérer la connexion à partir d’un exemple de service :

public class ExampleService(
    [FromKeyedServices("chat")] IDistributedCache chatCache,
    [FromKeyedServices("product")] IDistributedCache productCache)
{
    // Use caches...
}

Pour plus d’informations sur les services à clé, consultez .NET injection de dépendances : services à clé.

Configuration

L’intégration de la mise en cache distribuée .NET AspireRedis fournit plusieurs options pour configurer la connexion Redis en fonction des exigences et des conventions de votre projet.

Utiliser une chaîne de connexion

Lorsque vous utilisez une chaîne de connexion à partir de la section de configuration ConnectionStrings, vous pouvez fournir le nom de la chaîne de connexion lors de l’appel de builder.AddRedisDistributedCache:

builder.AddRedisDistributedCache("cache");

Ensuite, la chaîne de connexion est récupérée à partir de la section de configuration ConnectionStrings :

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

Pour plus d’informations sur la mise en forme de cette chaîne de connexion, consultez la documentation de configuration RedisStack Exchange.

Utiliser des fournisseurs de configuration

L’intégration de mise en cache distribuée .NET Aspire Stack Exchange Redis prend en charge Microsoft.Extensions.Configuration. Il charge le StackExchangeRedisSettings à partir de la configuration à l’aide de la clé Aspire:StackExchange:Redis. Exemple appsettings.json qui configure certaines des options suivantes :

{
  "Aspire": {
    "StackExchange": {
      "Redis": {
        "ConfigurationOptions": {
          "ConnectTimeout": 3000,
          "ConnectRetry": 2
        },
        "DisableHealthChecks": true,
        "DisableTracing": false
      }
    }
  }
}

Pour obtenir le schéma complet d'intégration du client de mise en cache distribuée RedisJSON, consultez Aspire.StackExchange.Redis.DistributedCaching/ConfigurationSchema.json.

Utiliser des délégués en ligne

Vous pouvez également transmettre le délégué Action<StackExchangeRedisSettings> pour configurer certaines ou toutes les options en ligne, par exemple pour configurer DisableTracing:

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

Vous pouvez également configurer le ConfigurationOptions à l’aide du paramètre délégué Action<ConfigurationOptions> configureOptions de la méthode AddRedisDistributedCache. Par exemple, pour définir le délai d’expiration de la connexion :

builder.AddRedisDistributedCache(
    "cache",
    static settings => settings.ConnectTimeout = 3_000);

Client contrôles de santé de l’intégration

Par défaut, les intégrations de clients .NET.NET Aspire ont les contrôles de santé activés pour tous les services. De même, de nombreuses intégrations d'hébergement .NET.NET Aspire activent également les endpoints de vérification de santé. Pour plus d’informations, consultez :

L’intégration de la mise en cache distribuée .NET AspireRedis gère les opérations suivantes :

  • Ajoute le contrôle de santé lorsque StackExchangeRedisSettings.DisableHealthChecks est false, afin de tenter de se connecter à l’instance de conteneur.
  • S’intègre au point de terminaison HTTP /health, qui spécifie que tous les contrôles de santé enregistrés doivent être réussis pour que l'application soit prête à recevoir du trafic.

Observabilité et télémétrie

Les intégrations automatiques .NET.NET Aspire mettent en place la journalisation, le traçage et les mesures, parfois appelés les piliers de l’observabilité. Pour plus d’informations sur l’observabilité de l’intégration et la télémétrie, consultez .NET.NET Aspire vue d’ensemble des intégrations. Selon le service de stockage, certaines intégrations peuvent uniquement prendre en charge certaines de ces fonctionnalités. Par exemple, certaines intégrations prennent en charge la journalisation et le suivi, mais pas les métriques. Les fonctionnalités de télémétrie peuvent également être désactivées à l’aide des techniques présentées dans la section Configuration.

Exploitation forestière

L’intégration de mise en cache distribuée .NET AspireRedis utilise les catégories de journalisation suivantes :

  • Aspire.StackExchange.Redis
  • Microsoft.Extensions.Caching.StackExchangeRedis

Traçage

L’intégration de la mise en cache distribuée .NET AspireRedis émet les activités de suivi suivantes à l’aide de OpenTelemetry:

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Métriques

L’intégration de la mise en cache distribuée .NET AspireRedis ne prend actuellement pas en charge les métriques par défaut en raison de limitations avec la bibliothèque StackExchange.Redis.

Voir aussi

*: Redis est une marque déposée de Redis Ltd. Tous les droits qu’il contient sont réservés à Redis Ltd. Toute utilisation par Microsoft est destinée à des fins référentielles uniquement et n’indique pas de parrainage, d’approbation ou d’affiliation entre Redis et Microsoft. Revenir au premier?