Sdílet prostřednictvím

.NET Aspire Azure Cache for Redis®* integrace

  • Článek

zahrnuje:integrace hostingu a integraceClient

Azure Cache for Redis poskytuje úložiště dat v paměti založené na Redis softwaru. Redis zlepšuje výkon a škálovatelnost aplikace, která využívá vysoce úložiště back-endových dat. Dokáže zpracovávat velké objemy požadavků aplikací tím, že uchovává často přístupná data v paměti serveru, která se dají zapsat a číst rychle. Redis přináší do moderních aplikací kritické řešení úložiště dat s nízkou latencí a vysokou propustností.

Azure Cache for Redis nabízí Redis open source (OSS Redis) i komerční produkt od společnosti Redis Inc. (Redis Enterprise) jako spravovanou službu. Poskytuje zabezpečenou a vyhrazenou instanci serveru Redis a úplnou kompatibilitu Redis rozhraní API. Společnost Microsoft provozuje službu hostované na Azurea může ji používat jakákoli aplikace v rámci Azurenebo mimo Azure.

Integrace .NET AspireAzure Cache for Redis umožňuje připojit se k existujícím instancím Azure Cache for Redis nebo vytvořit nové instance nebo spustit jako kontejner místně z .NET pomocí image kontejneru docker.io/library/redis.

Integrace hostování

Modely integrace hostování .NET AspireAzure Cache for Redis modelují prostředek AzureRedis jako typ AzureRedisCacheResource. Pokud chcete získat přístup k tomuto typu a rozhraním API pro jejich vyjádření jako prostředků v projektu hostitele aplikace , přidejte balíček NuGet 📦Aspire.Hosting.Azure.Redis:

dotnet add package Aspire.Hosting.Azure.Redis

Další informace najdete v tématu dotnet add package nebo Manage package dependencies in .NET applications.

Přidej prostředky AzureAzure Cache for Redis

Ve vašem projektu aplikace hostitele zavolejte AddAzureRedis na instanci builder a přidejte prostředek AzureAzure Cache for Redis, jak je uvedeno v následujícím příkladu:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Předchozí volání AddAzureRedis nakonfiguruje prostředek serveru Redis k nasazení jako Azure Cache for Redis.

Důležitý

Ve výchozím nastavení AddAzureRedis konfiguruje ověřování ID Microsoft Entra . To vyžaduje změny aplikací, které se potřebují připojit k těmto prostředkům, například integrace klientů.

Spropitné

Když voláte AddAzureRedis, implicitně volá AddAzureProvisioning– což přidává podporu pro generování Azure prostředků dynamicky během spouštění aplikace. Aplikace musí nakonfigurovat příslušné předplatné a umístění. Další informace naleznete pod Místní zřizování: Konfigurace.

Vygenerované přidělování Bicep

Pokud s Bicep začínáte, jedná se o doménově specifický jazyk pro definování prostředků Azure. S .NET.NET Aspirenemusíte psát Bicep ručně, zřizovací rozhraní API ho generuje automaticky za vás. Když publikujete svou aplikaci, vygenerovaný Bicep je zobrazen společně se souborem manifestu. Když přidáte prostředek AzureAzure Cache for Redis, vygeneruje se následující Bicep:

@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'

Předchozí Bicep je modul, který zřizuje AzureAzure Cache for Redis s následujícími výchozími nastaveními:

  • location: Umístění zdroje AzureAzure Cache for Redis Výchozí hodnota je umístění skupiny prostředků.
  • principalId: Hlavní ID zdroje AzureAzure Cache for Redis.
  • principalName: Hlavní název zdroje AzureAzure Cache for Redis.
  • sku: Číslo skladové položky zdroje AzureAzure Cache for Redis. Výchozí hodnota je Basic s kapacitou 1.
  • enableNonSslPort: Port jiného typu než SSL prostředku AzureAzure Cache for Redis. Výchozí hodnota je false.
  • disableAccessKeyAuthentication: Ověřování přístupového klíče prostředku AzureAzure Cache for Redis Výchozí hodnota je true.
  • minimumTlsVersion: Minimální verze protokolu TLS prostředku AzureAzure Cache for Redis. Výchozí hodnota je 1.2.
  • redisConfiguration: Konfigurace Redis prostředku Azure Cache for Redis. Výchozí hodnota je aad-enabled nastavená na true.
  • tags: Štítky prostředku AzureAzure Cache for Redis. Výchozí hodnota je aspire-resource-name nastavena podle názvu zdroje Aspire, v tomto případě redis.
  • redis_contributor: Přispěvatel zdroje AzureAzure Cache for Redis, který má název přístupové politiky Data Contributor.
  • connectionString: Připojovací řetězec prostředku AzureAzure Cache for Redis.

Kromě AzureAzure Cache for Rediszajišťuje také přiřazení zásad přístupu k aplikaci mající přístup k mezipaměti. Vygenerovaný Bicep je výchozím bodem a můžete ho přizpůsobit tak, aby splňoval vaše konkrétní požadavky.

Přizpůsobení provisní infrastruktury

Všechny zdroje .NET AspireAzure jsou podtřídy typu AzureProvisioningResource. Tento typ umožňuje přizpůsobení vygenerovaného skriptu Bicep tím, že poskytuje plynulé API pro konfiguraci Azure prostředků pomocí API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Můžete například nakonfigurovat kind, consistencyPolicy, locationsatd. Následující příklad ukazuje, jak přizpůsobit zdroj 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");
    });

Předchozí kód:

Pro přizpůsobení prostředku AzureAzure Cache for Redis je k dispozici mnoho dalších možností konfigurace. Další informace najdete v tématu Azure.Provisioning.Redis. Další informace najdete v tématu Azure. Zřizování přizpůsobení.

Připojte se k existujícímu AzureAzure Cache for Redis

Možná máte existující AzureAzure Cache for Redis, k nimž se chcete připojit. Místo abyste vytvářeli nový prostředek AzureAzure Cache for Redis, můžete k hostiteli aplikace přidat připojovací řetězec. Pokud chcete přidat připojení k existujícímu AzureAzure Cache for Redis, zavolejte metodu 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...

Poznámka

Připojovací řetězce se používají k reprezentaci široké škály informací o připojení, včetně databázových připojení, zprostředkovatelů zpráv, identifikátorů URI koncových bodů a dalších služeb. V .NET.NET Aspire terminologii se výraz "připojovací řetězec" používá k reprezentaci jakéhokoli druhu informací o připojení.

Připojovací řetězec se konfiguruje v konfiguraci hostitele aplikace, obvykle v části Tajné kódy uživatelův části ConnectionStrings. Hostitel aplikace vloží tento připojovací řetězec jako proměnnou prostředí do všech závislých prostředků, například:

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

Závislý prostředek může mít přístup k vloženému připojovacímu řetězci voláním metody GetConnectionString a předáním názvu připojení jako parametru, v tomto případě "azure-redis". Rozhraní API GetConnectionString je zkráceným označením pro IConfiguration.GetSection("ConnectionStrings")[name].

Spuštění prostředku AzureAzure Cache for Redis jako kontejneru

Integrace hostování Azure Cache for Redis podporuje spuštění serveru Redis jako místního kontejneru. To je užitečné v situacích, kdy chcete spustit Redis server místně pro účely vývoje a testování, abyste se vyhnuli nutnosti zřídit Azure prostředek nebo se připojit k existujícímu Azure Cache for Redis serveru.

Pokud chcete použít image kontejneru docker.io/library/redis a spustit instanci AzureAzure Cache for Redis jako kontejner místně, zřetězte volání RunAsContainer, jak je znázorněno v následujícím příkladu:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Předchozí kód nakonfiguruje prostředek Redis tak, aby se spustil místně v kontejneru.

Spropitné

Metoda RunAsContainer je užitečná pro místní vývoj a testování. Rozhraní API zveřejňuje volitelný delegát, který umožňuje přizpůsobit základní konfiguraci RedisResource, například přidání Redis Insights, Redis Commander, přidání datového svazku nebo připojení datové vazby. Další informace naleznete v integraci hostování .NET AspireRedis.

Nakonfigurujte prostředek AzureAzure Cache for Redis tak, aby používal ověřování pomocí přístupového klíče.

Ve výchozím nastavení je prostředek AzureAzure Cache for Redis nakonfigurovaný tak, aby používal ověřování ID Microsoft Entra. Pokud chcete použít ověřování heslem (nedoporučuje se), můžete server nakonfigurovat tak, aby používal ověřování heslem voláním metody 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...

Předchozí kód nakonfiguruje prostředek AzureAzure Cache for Redis tak, aby používal ověřování pomocí přístupového klíče. Tím se vygenerovaný Bicep změní tak, aby místo ověřování pomocí Microsoft Entra ID používal ověřování pomocí přístupového klíče. Jinými slovy, připojovací řetězec bude obsahovat heslo a bude přidán do Azure Key Vault tajného kódu.

integrace Client

Pokud chcete začít s integrací klienta .NET Aspire Stack Exchange Redis, nainstalujte 📦Aspire. StackExchange.Redis balíček NuGet v projektu, který využívá klienta, to znamená projekt aplikace, která používá klienta Redis. Integrace klienta Redis registruje instanci IConnectionMultiplexer, kterou můžete použít k interakci s Redis.

dotnet add package Aspire.StackExchange.Redis

Přidejte klienta Redis

V souboru Program.cs projektu, který využívá klienta, zavolejte metodu rozšíření AddRedisClient na libovolném IHostApplicationBuilder a zaregistrujte IConnectionMultiplexer pro použití prostřednictvím kontejneru injektáže závislostí. Metoda přebírá parametr názvu připojení.

builder.AddRedisClient(connectionName: "cache");

Spropitné

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku AzureAzure Cache for Redis do hostitelského projektu aplikace. Další informace najdete v části Přidání AzureAzure Cache for Redis prostředků.

Potom můžete načíst instanci IConnectionMultiplexer pomocí injekce závislostí. Pokud například chcete načíst připojení z ukázkové služby:

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

Další informace o injektáži závislostí najdete v tématu .NET injektáž závislostí.

Přidejte AzureAzure Cache for Redis ověřeného klienta

Ve výchozím nastavení, když voláte AddAzureRedis v integraci hostování Redis, nakonfiguruje Microsoft Entra ID. Nainstalujte 📦 Microsoft.Azure.StackExchangeRedis NuGet balíček pro povolení ověřování:

dotnet add package Microsoft.Azure.StackExchangeRedis

Připojení Redis lze využívat pomocí integrace klienta a Microsoft.Azure.StackExchangeRedis. Zvažte následující konfigurační kód:

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;
});

Další informace najdete v Microsoft.Azure. StackExchangeRedis repo.

Přidání klienta Redis s klíči

V situacích, kdy chcete zaregistrovat více instancí IConnectionMultiplexer s různými názvy připojení. Pokud chcete zaregistrovat klíčované klienty Redis, zavolejte metodu AddKeyedRedisClient:

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

Potom můžete pomocí injekce závislostí načíst instance IConnectionMultiplexer. Pokud například chcete načíst připojení z ukázkové služby:

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

Další informace o klíčových službách najdete v tématu .NET injektáž závislostí: Služby s klíči.

Konfigurace

Integrace klienta .NET Aspire Stack Exchange Redis nabízí několik možností konfigurace připojení Redis na základě požadavků a konvencí projektu.

Použití připojovacího řetězce

Při použití připojovacího řetězce z oddílu konfigurace ConnectionStrings můžete při volání AddRediszadat název připojovacího řetězce:

builder.AddRedis("cache");

Pak se načte připojovací řetězec z oddílu konfigurace ConnectionStrings.

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

Další informace o tom, jak formátovat tento připojovací řetězec, najdete v dokumentaci ke konfiguraci Stack Exchange Redis.

Použití zprostředkovatelů konfigurace

Integrace .NET Aspire Stack Exchange Redis podporuje Microsoft.Extensions.Configuration. Načte StackExchangeRedisSettings z konfigurace pomocí klíče Aspire:StackExchange:Redis. Příklad appsettings.json, který konfiguruje některé z možností:

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

Pro úplné schéma integrace klienta RedisJSON se podívejte na Aspire.StackExchange.Redis/ConfigurationSchema.json.

Použití vložených delegátů

Můžete také předat delegáta Action<StackExchangeRedisSettings>, abyste nastavili některé nebo všechny možnosti přímo, například pro konfiguraci DisableTracing:

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

Client kontroly stavu integrace

Ve výchozím nastavení .NET.NET Aspireklientské integrace mají kontroly stavu povoleny pro všechny služby. Podobně mnoho .NET.NET Aspirehostování integrací také povoluje koncové body kontroly stavu. Další informace najdete tady:

Integrace .NET Aspire Stack Exchange Redis zpracovává následující:

  • Přidá kontrolu stavu při StackExchangeRedisSettings.DisableHealthChecks je false, která se pokusí připojit k instanci kontejneru.
  • Integruje se s koncovým bodem HTTP /health, který určuje, že všechny registrované kontroly stavu musí být úspěšné, aby byla aplikace považována za připravenou přijímat provoz.

Pozorovatelnost a telemetrie

.NET .NET Aspire integrace automaticky nastaví konfigurace protokolování, trasování a metrik, které se někdy označují jako pilířů pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.

Protokolování

Integrace .NET Aspire Stack Exchange Redis používá následující kategorie protokolů:

  • Aspire.StackExchange.Redis

Trasování

Integrace .NET Aspire Stack Exchange Redis bude generovat následující aktivity trasování pomocí OpenTelemetry:

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Ukazatele

Integrace .NET Aspire Stack Exchange Redis aktuálně nepodporuje metriky ve výchozím nastavení kvůli omezením knihovny StackExchange.Redis.

Viz také

*: Redis je registrovaná ochranná známka společnosti Redis Ltd. Všechna práva v nich jsou vyhrazena pro Redis Ltd. Jakékoli použití společností Microsoft je určené pouze pro referenční účely a nezoznačuje žádné sponzorství, doporučení ani přidružení mezi Redis a Microsoftem. Návrat na horní?