Partager via

® intégration de la mise en cache distribuée .NET AspireAzure Cache for Redis*

  • Article

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

Azure Cache for Redis fournit un magasin de données en mémoire basé sur le logiciel Redis. Redis améliore considérablement les performances et l’extensibilité d’une application qui utilise des magasins de données principaux. Il est en mesure de traiter de grands volumes de demandes d’application en conservant rapidement les données fréquemment consultées dans la mémoire du serveur, qui peuvent être écrites et lues rapidement. Redis apporte une solution de stockage de données à faible latence et à débit élevé critique aux applications modernes.

Azure Cache for Redis propose à la fois le Redis open source (OSS Redis) et un produit commercial de Redis Inc. (Redis Enterprise) en tant que service géré. Il fournit des instances de serveur Redis sécurisées et dédiées et une compatibilité complète des API Redis. Microsoft exploite le service, hébergé sur Azureet utilisable par n’importe quelle application au sein ou en dehors de Azure.

L’intégration .NET AspireAzure Cache for Redis vous permet de vous connecter à des instances de Azure Cache for Redis existantes ou de créer de nouvelles instances à partir de .NET avec l’image conteneur docker.io/library/redis.

Intégration de l’hébergement

Le modèle d'intégration .NET AspireAzure Cache for Redis configure une ressource AzureRedis comme un type de AzureRedisCacheResource. Pour accéder à ce type et aux API pour les présenter en tant que ressources dans le projet hôte d’application , ajoutez le package NuGet 📦Aspire.Hosting.Azure.Redis :

dotnet add package Aspire.Hosting.Azure.Redis

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

Ajouter une ressource AzureAzure Cache for Redis

Dans votre projet hôte d’application, appelez AddAzureRedis sur l’instance de builder pour ajouter une ressource AzureAzure Cache for Redis, comme illustré dans l’exemple suivant :

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddAzureRedis("azcache");

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

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

L’appel précédent à AddAzureRedis configure la ressource de serveur Redis à déployer en tant que Azure Cache for Redis.

Important

Par défaut, AddAzureRedis configure l’authentification Microsoft Entra ID. Cela nécessite des modifications apportées aux applications qui doivent se connecter à ces ressources, par exemple des intégrations clientes.

Pourboire

Lorsque vous appelez AddAzureRedis, il appelle implicitement AddAzureProvisioning, ce qui ajoute la prise en charge de la génération dynamique de ressources Azure pendant le démarrage de l’application. L’application doit configurer l’abonnement et l’emplacement appropriés. Pour plus d’informations, consultez approvisionnement local : Configuration.

Approvisionnement généré Bicep

Si vous débutez avec Bicep, c'est un langage de domaine spécifique pour la définition des ressources Azure. Avec .NET.NET Aspire, vous n’avez pas besoin d’écrire Bicep manuellement, au lieu de cela, les API d’approvisionnement génèrent Bicep pour vous. Lorsque vous publiez votre application, le Bicep généré est produit en même temps que le fichier manifeste. Lorsque vous ajoutez une ressource AzureAzure Cache for Redis, le Bicep suivant est généré :

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param principalId string

param principalName string

resource redis 'Microsoft.Cache/redis@2024-03-01' = {
  name: take('redis-${uniqueString(resourceGroup().id)}', 63)
  location: location
  properties: {
    sku: {
      name: 'Basic'
      family: 'C'
      capacity: 1
    }
    enableNonSslPort: false
    disableAccessKeyAuthentication: true
    minimumTlsVersion: '1.2'
    redisConfiguration: {
      'aad-enabled': 'true'
    }
  }
  tags: {
    'aspire-resource-name': 'redis'
  }
}

resource redis_contributor 'Microsoft.Cache/redis/accessPolicyAssignments@2024-03-01' = {
  name: take('rediscontributor${uniqueString(resourceGroup().id)}', 24)
  properties: {
    accessPolicyName: 'Data Contributor'
    objectId: principalId
    objectIdAlias: principalName
  }
  parent: redis
}

output connectionString string = '${redis.properties.hostName},ssl=true'

Bicep précédent est un module qui provisionne un AzureAzure Cache for Redis avec les valeurs par défaut suivantes :

  • location: emplacement de la ressource AzureAzure Cache for Redis. La valeur par défaut est l’emplacement du groupe de ressources.
  • principalId: ID principal de la ressource AzureAzure Cache for Redis.
  • principalName: Le nom principal de la ressource AzureAzure Cache for Redis.
  • sku: référence SKU de la ressource AzureAzure Cache for Redis. La valeur par défaut est Basic avec une capacité de 1.
  • enableNonSslPort: port non SSL de la ressource AzureAzure Cache for Redis. La valeur par défaut est false.
  • disableAccessKeyAuthentication: Authentification de la clé d’accès de la ressource AzureAzure Cache for Redis. La valeur par défaut est true.
  • minimumTlsVersion: version TLS minimale de la ressource AzureAzure Cache for Redis. La valeur par défaut est 1.2.
  • redisConfiguration: configuration Redis de la ressource Azure Cache for Redis. La valeur par défaut est aad-enabled définie sur true.
  • tags: les balises de la ressource AzureAzure Cache for Redis. La valeur par défaut est aspire-resource-name définie sur le nom de la ressource Aspire, dans ce cas redis.
  • redis_contributor: le contributeur de la ressource AzureAzure Cache for Redis, avec le nom de stratégie d’accès Data Contributor.
  • connectionString: chaîne de connexion de la ressource AzureAzure Cache for Redis.

Outre le AzureAzure Cache for Redis, il assure également l'attribution d'une stratégie d'accès pour l'application afin d'accéder au cache. Bicep généré est un point de départ et peut être personnalisé pour répondre à vos besoins spécifiques.

Personnaliser l’infrastructure d’approvisionnement

Toutes les ressources .NET AspireAzure sont des sous-classes du type AzureProvisioningResource. Ce type permet la personnalisation du Bicep généré en fournissant une API fluide pour configurer les ressources Azure à l’aide de l’API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Par exemple, vous pouvez configurer le kind, consistencyPolicy, locations, etc. L’exemple suivant montre comment personnaliser la ressource AzureAzure Cache for Redis :

builder.AddAzureRedis("redis")
    .WithAccessKeyAuthentication()
    .ConfigureInfrastructure(infra =>
    {
        var redis = infra.GetProvisionableResources()
                         .OfType<RedisResource>()
                         .Single();

        redis.Sku = new()
        {
            Family = RedisSkuFamily.BasicOrStandard,
            Name = RedisSkuName.Standard,
            Capacity = 1,                    
        };
        redis.Tags.Add("ExampleKey", "Example value");
    });

Code précédent :

  • Chaîne un appel à l’API ConfigureInfrastructure :
    • Le paramètre infra est une instance du type AzureResourceInfrastructure.
    • Les ressources provisionnables sont récupérées en appelant la méthode GetProvisionableResources().
    • Le numéro unique RedisResource est récupéré.
    • Le Sku est défini avec une famille de BasicOrStandard, un nom de Standardet une capacité de 1.
    • Une balise est ajoutée à la ressource Redis avec une clé de ExampleKey et une valeur de Example value.

Il existe de nombreuses autres options de configuration disponibles pour personnaliser la ressource AzureAzure Cache for Redis. Pour plus d’informations, consultez Azure.Provisioning.Redis. Pour plus d’informations, consultez Azure. Personnalisation de l’approvisionnement.

Se connecter à un AzureAzure Cache for Redis existant

Vous pouvez avoir un AzureAzure Cache for Redis existant auquel vous souhaitez vous connecter. Au lieu de représenter une nouvelle ressource AzureAzure Cache for Redis, vous pouvez ajouter une chaîne de connexion à l’hôte de l’application. Pour ajouter une connexion à un AzureAzure Cache for Redisexistant, appelez la méthode AddConnectionString :

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddConnectionString("azure-redis");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(cache);

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

Note

Les chaînes de connexion sont utilisées pour représenter un large éventail d’informations de connexion, notamment les connexions de base de données, les répartiteurs de messages, les URI de point de terminaison et d’autres services. Dans .NET.NET Aspire nomenclature, le terme « chaîne de connexion » est utilisé pour représenter n’importe quel type d’informations de connexion.

La chaîne de connexion est configurée dans la configuration de l’hôte d’application, généralement sous secrets utilisateur, sous la section ConnectionStrings. L’hôte de l’application injecte cette chaîne de connexion en tant que variable d’environnement dans toutes les ressources dépendantes, par exemple :

{
    "ConnectionStrings": {
        "azure-redis": "<your-redis-name>.redis.cache.windows.net:6380,ssl=true,abortConnect=False"
    }
}

La ressource dépendante peut accéder à la chaîne de connexion injectée en appelant la méthode GetConnectionString et en passant le nom de connexion en tant que paramètre, dans ce cas "azure-redis". L’API GetConnectionString est abrégée pour IConfiguration.GetSection("ConnectionStrings")[name].

Exécuter AzureAzure Cache for Redis ressource en tant que conteneur

L’intégration d’hébergement Azure Cache for Redis prend en charge l’exécution du serveur Redis en tant que conteneur local. Cela est bénéfique pour les situations où vous souhaitez exécuter le serveur Redis localement à des fins de développement et de test, en évitant la nécessité de provisionner une ressource Azure ou de vous connecter à un serveur Azure Cache for Redis existant.

Pour utiliser l’image conteneur docker.io/library/redis et exécuter l’instance AzureAzure Cache for Redis en tant que conteneur localement, chaînez un appel à RunAsContainer, comme illustré dans l’exemple suivant :

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddAzureRedis("azcache")
                   .RunAsContainer();

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

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

Le code précédent configure la ressource Redis pour qu’elle s’exécute localement dans un conteneur.

Pourboire

La méthode RunAsContainer est utile pour le développement et les tests locaux. L'API met à disposition un délégué facultatif qui vous permet de personnaliser la configuration sous-jacente de RedisResource, par exemple en ajoutant Redis Insights, Redis Commander, ou un volume de données ou un montage de liaison de données. Pour plus d’informations, consultez l'intégration de l'hébergement avec les références .NET AspireRedis et.

Configurer la ressource AzureAzure Cache for Redis pour utiliser l’authentification par clé d’accès

Par défaut, la ressource AzureAzure Cache for Redis est configurée pour utiliser l'authentification Microsoft Entra ID. Si vous souhaitez utiliser l’authentification par mot de passe (non recommandé), vous pouvez configurer le serveur pour qu’il utilise l’authentification par mot de passe en appelant la méthode WithAccessKeyAuthentication :

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddAzureRedis("azcache")
                   .WithAccessKeyAuthentication();

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

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

Le code précédent configure la ressource AzureAzure Cache for Redis pour utiliser l’authentification par clé d’accès. Cela modifie le Bicep généré pour utiliser l’authentification par clé d’accès au lieu de l’authentification Microsoft Entra ID. En d’autres termes, la chaîne de connexion contiendra un mot de passe et sera ajoutée à un secret Azure Key Vault.

intégration de 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 de cache distribué

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 AzureAzure Cache for Redis dans le projet hôte de l’application. Pour plus d’informations, consultez AzureAzure Cache for Redis ajouter la ressource.

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 AzureAzure Cache for Redis client distribué authentifié

Par défaut, lorsque vous appelez AddAzureRedis dans votre projet hôte d’application, l’intégration d’hébergement Redis configure 📦 Microsoft.Azure. StackExchangeRedis package NuGet pour activer l’authentification :

dotnet add package Microsoft.Azure.StackExchangeRedis

La connexion Redis peut être consommée à l’aide de l’intégration du client et Microsoft.Azure.StackExchangeRedis. Tenez compte du code de configuration suivant :

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.AddRedisDistributedCache("cache", configureOptions: options =>
{
    options.Defaults = configurationOptions.Defaults;
});

Pour plus d’informations, consultez le dépôt Microsoft.Azure.StackExchangeRedis.

Ajouter un client Redis clé

Il peut arriver que vous souhaitiez inscrire plusieurs instances de IDistributedCache avec différents noms de connexion. Pour enregistrer les clients à clé Redis, appelez 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 les docs de configuration Stack Exchange Redis.

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 effectue le chargement du StackExchangeRedisSettings depuis la configuration en utilisant 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 de mise en cache distribuée du client RedisJSON, consultez Aspire.StackExchange.Redis.DistributedCaching/ConfigurationSchema.json.

Utiliser des délégués intégrés

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

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

Vous pouvez également configurer les options de configuration à 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 vérifications de santé de l’intégration

Par défaut, les intégrations clients .NET.NET Aspire ont des 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 points de terminaison de vérification d’intégrité. Pour plus d’informations, consultez :

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

  • Ajoute la vérification d’intégrité lorsque StackExchangeRedisSettings.DisableHealthChecks est false, qui tente de se connecter à l’instance de conteneur.
  • S’intègre au point de terminaison HTTP /health, qui spécifie que toutes les vérifications d’intégrité inscrites doivent passer pour que l’application soit considérée comme prête à accepter le trafic.

Observabilité et télémétrie

.NET .NET Aspire intégrations configurent automatiquement les configurations de journalisation, de suivi et de métriques, parfois appelées 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 log 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?