Partager via

.NET Aspire Azure Cache for Redis * ® intégration

  • Article

inclut : l’intégration d’hébergement et l’intégration de 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 Azure Cache for Redis existantes, ou de créer de nouvelles instances, ou de s’exécuter en tant que conteneur localement à partir de .NET avec l’image conteneur docker.io/library/redis.

Intégration de l’hébergement

Le modèle d’intégration d’hébergement conçoit une ressource AzureRedis comme un type AzureRedisCacheResource. Pour accéder à ce type et à ces API pour les exprimer en tant que ressources dans votre projet hôte d'application , ajoutez le pack NuGet 📦Aspire.Hébergement.Azure.Redis :

dotnet add package Aspire.Hosting.Azure.Redis

Pour plus d’informations, consultez dotnet add package ou Manage package dependencies in .NET applications.

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 Provisionnement local : Configuration.

Provisionnement généré Bicep

Si vous débutez avec Bicep, c'est un langage spécifique au domaine utilisé pour définir 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 fourni avec 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: 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 la politique d'accès Data Contributor.
  • connectionString: chaîne de connexion de la ressource AzureAzure Cache for Redis.

Outre le AzureAzure Cache for Redis, il configure également une politique d'accès à l'application pour 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 fichier 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 RedisResource unique 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 expose un délégué facultatif qui vous permet de personnaliser la configuration de RedisResource sous-jacente, par exemple l’ajout de Redis Insights, Redis Commander, l’ajout d’un volume de données ou d’un montage de liaison de données. Pour plus d'informations, consultez l'intégration d'hébergement .NET AspireRedis.

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 avec l’intégration du client .NET Aspire Stack Exchange Redis, installez le package NuGet 📦Aspire.StackExchange.Redis dans le projet qui consomme le client, c’est-à-dire le projet pour l’application qui utilise le client Redis. L’intégration du client Redis inscrit une instance IConnectionMultiplexer que vous pouvez utiliser pour interagir avec Redis.

dotnet add package Aspire.StackExchange.Redis

Ajouter Redis client

Dans le fichier Program.cs de votre projet consommant le client, appelez la méthode d’extension AddRedisClient sur n’importe quelle IHostApplicationBuilder pour inscrire un IConnectionMultiplexer à utiliser via le conteneur d’injection de dépendances. La méthode prend un paramètre de nom de connexion.

builder.AddRedisClient(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 ressource.

Vous pouvez ensuite récupérer l’instance IConnectionMultiplexer à 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(IConnectionMultiplexer connectionMux)
{
    // Use connection multiplexer...
}

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

Ajouter AzureAzure Cache for Redis client authentifié

Par défaut, lorsque vous appelez AddAzureRedis dans votre intégration d’hébergement Redis, il configure l’ID Microsoft Entra. Installez le 📦 Microsoft.Azure. StackExchangeRedis package NuGet pour activer l’authentification :

dotnet add package Microsoft.Azure.StackExchangeRedis

La connexion Redis peut être utilisée via l’intégration du client et avec 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.AddRedisClient("cache", configureOptions: options =>
{
    options.Defaults = configurationOptions.Defaults;
});

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

Ajouter un client Redis associé

Il peut arriver que vous souhaitiez inscrire plusieurs instances de IConnectionMultiplexer avec différents noms de connexion. Pour enregistrer les clients enregistrés avec Redis, appelez la méthode AddKeyedRedisClient :

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

Vous pouvez ensuite récupérer les instances IConnectionMultiplexer à 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")] IConnectionMultiplexer chatConnectionMux,
    [FromKeyedServices("queue")] IConnectionMultiplexer queueConnectionMux)
{
    // Use connections...
}

Pour plus d'informations sur les services identifiés par clé, consultez .NET injection de dépendances : services identifiés par clé.

Configuration

L’intégration du client .NET Aspire Stack Exchange Redis offre 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 AddRedis:

builder.AddRedis("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 .NET Aspire Stack Exchange Redis prend en charge Microsoft.Extensions.Configuration. Il charge le StackExchangeRedisSettings à partir de 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 de l’intégration du client RedisJSON, consultez Aspire.StackExchange.Redis/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 directement, par exemple pour configurer DisableTracing:

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

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 .NET Aspire Stack Exchange Redis 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

.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 .NET Aspire Stack Exchange Redis utilise les catégories de journalisation suivantes :

  • Aspire.StackExchange.Redis

Traçage

L’intégration .NET Aspire Stack Exchange Redis émettra les activités de suivi suivantes à l’aide de OpenTelemetry:

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Métriques

L’intégration .NET Aspire Stack Exchange Redis ne prend actuellement pas en charge les métriques par défaut en raison de limitations avec la bibliothèque de 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?