Baca dalam bahasa Inggris

Bagikan melalui

.NET Aspire Azure Cache for Redis®* integrasi

  • Artikel

Meliputi: integrasi hosting dan integrasi Client

Azure Cache for Redis menyediakan penyimpanan data dalam memori berdasarkan perangkat lunak Redis. Redis meningkatkan performa dan skalabilitas aplikasi yang sangat menggunakan penyimpanan data backend. Ini dapat memproses permintaan aplikasi dalam volume besar dengan menyimpan data yang sering diakses dalam memori server, yang dapat ditulis dan dibaca dari dengan cepat. Redis menghadirkan solusi penyimpanan data latensi rendah dan throughput tinggi yang penting untuk aplikasi modern.

Azure Cache for Redis menawarkan sumber terbuka Redis (RedisOSS) dan produk komersial dari Redis Inc. (Redis Enterprise) sebagai layanan terkelola. Ini menyediakan instans server Redis yang aman dan khusus dan kompatibilitas API Redis penuh. Microsoft mengoperasikan layanan, yang dihosting di Azure, dan dapat digunakan oleh aplikasi apa pun di dalam atau di luar Azure.

Integrasi .NET AspireAzure Cache for Redis memungkinkan Anda terhubung ke instans Azure Cache for Redis yang ada, atau membuat instans baru, atau menjalankan sebagai kontainer secara lokal dari .NET dengan gambar kontainer docker.io/library/redis.

Integrasi hosting

Integrasi hosting .NET AspireAzure Cache for Redis memodelkan sumber daya AzureRedis sebagai jenis AzureRedisCacheResource. Untuk mengakses tipe dan API ini serta mendefinisikannya sebagai sumber daya dalam proyek host aplikasi Anda di, tambahkan paket NuGet 📦Aspire.Hosting.Azure.Redis.

.NET CLI 
dotnet add package Aspire.Hosting.Azure.Redis

Untuk informasi selengkapnya, lihat dotnet menambahkan paket atau Mengelola dependensi paket di aplikasi .NET.

Menambahkan sumber daya AzureAzure Cache for Redis

Di proyek host aplikasi Anda, panggil AddAzureRedis pada instans builder untuk menambahkan sumber daya AzureAzure Cache for Redis, seperti yang ditunjukkan dalam contoh berikut:

C# 
var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Panggilan sebelumnya ke AddAzureRedis mengonfigurasi sumber daya server Redis untuk disebarkan sebagai Azure Cache for Redis.

Penting

Secara default, AddAzureRedis mengonfigurasi autentikasi ID Microsoft Entra . Ini memerlukan perubahan pada aplikasi yang perlu terhubung ke sumber daya ini, misalnya, integrasi klien.

Tip

Saat Anda memanggil AddAzureRedis, secara implisit memanggil AddAzureProvisioning—yang menambahkan dukungan untuk menghasilkan sumber daya Azure secara dinamis selama pengaktifan aplikasi. Aplikasi harus mengonfigurasi langganan dan lokasi yang sesuai. Untuk informasi selengkapnya, lihat Penyediaan lokal: Konfigurasi.

Provisi yang dihasilkan untuk Bicep

Jika Anda baru menggunakan Bicep, ini adalah bahasa spesifik domain untuk menentukan sumber daya Azure. Dengan .NET.NET Aspire, Anda tidak perlu menulis Bicep secara manual, sebagai gantinya API provisi menghasilkan Bicep untuk Anda. Ketika Anda memublikasikan aplikasi Anda, Bicep yang dihasilkan dikeluarkan di samping file manifes. Saat Anda menambahkan sumber daya AzureAzure Cache for Redis, Bicep berikut dibuat:

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'

Bicep sebelumnya adalah modul yang menyediakan AzureAzure Cache for Redis dengan default berikut:

  • location: Lokasi sumber daya AzureAzure Cache for Redis. Defaultnya adalah lokasi grup sumber daya.
  • principalId: ID utama sumber daya AzureAzure Cache for Redis.
  • principalName: Nama utama sumber daya AzureAzure Cache for Redis.
  • sku: SKU sumber daya AzureAzure Cache for Redis. Defaultnya adalah Basic dengan kapasitas 1.
  • enableNonSslPort: Port non-SSL dari sumber daya AzureAzure Cache for Redis. Defaultnya adalah false.
  • disableAccessKeyAuthentication: Autentikasi kunci akses sumber daya AzureAzure Cache for Redis. Defaultnya adalah true.
  • minimumTlsVersion: Versi TLS minimum dari sumber daya AzureAzure Cache for Redis. Defaultnya adalah 1.2.
  • redisConfiguration: Konfigurasi Redis dari sumber daya Azure Cache for Redis. Defaultnya adalah aad-enabled diatur ke true.
  • tags: Tag sumber daya AzureAzure Cache for Redis. Defaultnya adalah aspire-resource-name yang diatur ke nama sumber daya Aspire, dalam hal ini adalah redis.
  • redis_contributor: Kontributor sumber daya AzureAzure Cache for Redis, dengan nama kebijakan akses Data Contributor.
  • connectionString: String koneksi sumber daya AzureAzure Cache for Redis.

Selain AzureAzure Cache for Redis, ini juga menyediakan penetapan kebijakan akses aplikasi ke cache. Bicep yang dihasilkan adalah titik awal dan dapat disesuaikan untuk memenuhi persyaratan spesifik Anda.

Menyesuaikan infrastruktur provisi

Semua sumber daya .NET AspireAzure adalah subkelas dari jenis AzureProvisioningResource. Jenis ini memungkinkan penyesuaian Bicep yang dihasilkan dengan menyediakan API yang fasih untuk mengonfigurasi sumber daya Azure—menggunakan API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Misalnya, Anda dapat mengonfigurasi kind, consistencyPolicy, locations, dan banyak lagi. Contoh berikut menunjukkan cara mengkustomisasi sumber daya AzureAzure Cache for Redis:

C# 
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");
    });

Kode sebelumnya:

Ada lebih banyak opsi konfigurasi yang tersedia untuk menyesuaikan sumber daya AzureAzure Cache for Redis. Untuk informasi selengkapnya, lihat Azure.Provisioning.Redis. Untuk informasi selengkapnya, lihat Azure. Penyesuaian provisi.

Menyambungkan ke AzureAzure Cache for Redis yang sudah ada

Anda mungkin memiliki AzureAzure Cache for Redis yang sudah ada untuk disambungkan. Alih-alih mewakili sumber daya AzureAzure Cache for Redis baru, Anda dapat menambahkan string koneksi ke host aplikasi. Untuk menambahkan koneksi ke AzureAzure Cache for Redisyang sudah ada, panggil metode AddConnectionString:

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

Catatan

String koneksi digunakan untuk mewakili berbagai informasi koneksi, termasuk koneksi database, broker pesan, URI titik akhir, dan layanan lainnya. Dalam nomenklatur .NET.NET Aspire, istilah "string koneksi" digunakan untuk mewakili segala jenis informasi koneksi.

String koneksi dikonfigurasi dalam konfigurasi host aplikasi, biasanya di bawah Rahasia Pengguna, di bawah bagian ConnectionStrings. Host aplikasi menyuntikkan string koneksi ini sebagai variabel lingkungan ke semua sumber daya dependen, misalnya:

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

Sumber daya dependen dapat mengakses string koneksi yang disuntikkan dengan memanggil metode GetConnectionString, dan meneruskan nama koneksi sebagai parameter, dalam hal ini "azure-redis". API GetConnectionString singkatan untuk IConfiguration.GetSection("ConnectionStrings")[name].

Menjalankan sumber daya AzureAzure Cache for Redis sebagai kontainer

Integrasi hosting Azure Cache for Redis mendukung menjalankan server Redis sebagai kontainer lokal. Ini bermanfaat untuk situasi di mana Anda ingin menjalankan server Redis secara lokal untuk tujuan pengembangan dan pengujian, menghindari kebutuhan untuk menyediakan sumber daya Azure atau terhubung ke server Azure Cache for Redis yang ada.

Untuk menggunakan gambar kontainer docker.io/library/redis, dan menjalankan instans AzureAzure Cache for Redis sebagai kontainer secara lokal, rantai panggilan ke RunAsContainer, seperti yang ditunjukkan dalam contoh berikut:

C# 
var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Kode sebelumnya mengonfigurasi sumber daya Redis untuk berjalan secara lokal dalam kontainer.

Tip

Metode RunAsContainer berguna untuk pengembangan dan pengujian lokal. API mengekspos delegasi opsional yang memungkinkan Anda menyesuaikan konfigurasi RedisResource yang mendasar, seperti menambahkan Redis Insights, Redis Commander, menambahkan volume data atau pemasangan ikatan data. Untuk informasi selengkapnya, lihat integrasi hosting .NET AspireRedis.

Mengonfigurasi sumber daya AzureAzure Cache for Redis untuk menggunakan autentikasi kunci akses

Secara default, sumber daya AzureAzure Cache for Redis dikonfigurasi untuk menggunakan autentikasi ID Microsoft Entra. Jika Anda ingin menggunakan autentikasi kata sandi (tidak disarankan), Anda dapat mengonfigurasi server untuk menggunakan autentikasi kata sandi dengan memanggil metode WithAccessKeyAuthentication:

C# 
var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Kode sebelumnya mengonfigurasi sumber daya AzureAzure Cache for Redis untuk menggunakan autentikasi kunci akses. Ini mengubah Bicep yang dihasilkan untuk menggunakan autentikasi kunci akses alih-alih autentikasi ID Microsoft Entra. Dengan kata lain, string koneksi akan berisi kata sandi, dan akan ditambahkan ke rahasia Azure Key Vault.

integrasi Client

Untuk memulai integrasi klien .NET Aspire Stack Exchange Redis, instal paket NuGet 📦Aspire.StackExchange.Redis di proyek yang menggunakan klien, yaitu proyek untuk aplikasi yang menggunakan klien Redis. Integrasi klien Redis mendaftarkan instans IConnectionMultiplexer yang dapat Anda gunakan untuk berinteraksi dengan Redis.

.NET CLI 
dotnet add package Aspire.StackExchange.Redis

Menambahkan klien Redis

Dalam file Program.cs proyek yang digunakan oleh klien Anda, panggil metode ekstensi AddRedisClient pada IHostApplicationBuilder apa pun untuk mendaftarkan IConnectionMultiplexer agar dapat digunakan melalui kontainer injeksi dependensi. Metode ini mengambil parameter nama koneksi.

C# 
builder.AddRedisClient(connectionName: "cache");

Tip

Parameter connectionName harus cocok dengan nama yang digunakan saat menambahkan sumber daya AzureAzure Cache for Redis dalam proyek host aplikasi. Untuk informasi selengkapnya, lihat Tambahan sumber daya AzureAzure Cache for Redis.

Kemudian, Anda dapat mengambil instans IConnectionMultiplexer dengan menggunakan injeksi dependensi. Misalnya, untuk mengambil koneksi dari layanan contoh:

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

Untuk informasi selengkapnya tentang injeksi dependensi, lihat .NET injeksi dependensi.

Menambahkan klien terautentikasi AzureAzure Cache for Redis

Secara default, saat Anda memanggil AddAzureRedis dalam integrasi hosting Redis Anda, itu mengonfigurasi ID Microsoft Entra. Instal paket NuGet 📦 Microsoft.Azure.StackExchangeRedis untuk mengaktifkan autentikasi.

.NET CLI 
dotnet add package Microsoft.Azure.StackExchangeRedis

Koneksi Redis dapat diakses menggunakan integrasi klien dan Microsoft.Azure.StackExchangeRedis. Pertimbangkan kode konfigurasi berikut:

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

Untuk informasi selengkapnya, lihat Microsoft.Azure. Repositori StackExchangeRedis.

Menambahkan klien dengan kunci Redis

Mungkin ada situasi di mana Anda ingin mendaftarkan beberapa instans IConnectionMultiplexer dengan nama koneksi yang berbeda. Untuk mendaftarkan klien bertipe Redis, panggil metode AddKeyedRedisClient:

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

Kemudian Anda dapat mengambil instance IConnectionMultiplexer menggunakan injeksi dependensi. Misalnya, untuk mengambil koneksi dari layanan contoh:

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

Untuk informasi selengkapnya tentang layanan utama, lihat .NET injeksi dependensi: Layanan utama.

Konfigurasi

Integrasi klien .NET Aspire Stack Exchange Redis menyediakan beberapa opsi untuk mengonfigurasi koneksi Redis berdasarkan persyaratan dan konvensi proyek Anda.

Menggunakan string koneksi

Saat menggunakan string koneksi dari bagian konfigurasi ConnectionStrings, Anda dapat memberikan nama string koneksi saat memanggil AddRedis:

C# 
builder.AddRedis("cache");

Kemudian string koneksi akan diambil dari bagian konfigurasi ConnectionStrings:

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

Untuk informasi selengkapnya tentang cara memformat string koneksi ini, lihat dokumen konfigurasi RedisStack Exchange.

Menggunakan penyedia konfigurasi

Integrasi .NET Aspire Stack Exchange Redis mendukung Microsoft.Extensions.Configuration. Menggunakan kunci Aspire:StackExchange:Redis untuk memuat StackExchangeRedisSettings dari konfigurasi. Contoh appsettings.json yang mengonfigurasi beberapa opsi:

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

Untuk skema JSON integrasi klien Redis lengkap, lihat Aspire. StackExchange.Redis/ConfigurationSchema.json.

Menggunakan delegasi sebaris

Anda juga dapat meneruskan delegasi Action<StackExchangeRedisSettings> untuk mengatur beberapa atau semua opsi secara langsung, misalnya untuk mengonfigurasi DisableTracing:

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

Client pemeriksaan kesehatan integrasi

Secara default, integrasi klien .NET.NET Aspire memiliki pemeriksaan kesehatan diaktifkan untuk semua layanan. Demikian pula, banyak integrasi hosting .NET.NET Aspire juga mengaktifkan titik akhir pemeriksaan kesehatan. Untuk informasi selengkapnya, lihat:

Integrasi .NET Aspire Stack Exchange Redis menangani hal berikut:

  • Menambahkan pemeriksaan kesehatan ketika StackExchangeRedisSettings.DisableHealthChecks menjadi false, yang berupaya menyambung ke instans kontainer.
  • Terintegrasi dengan endpoint HTTP /health, yang mengharuskan semua pemeriksaan kesehatan yang terdaftar harus lolos agar aplikasi dianggap siap untuk menerima lalu lintas.

Pengamatan dan telemetri

.NET .NET Aspire integrasi secara otomatis menyiapkan konfigurasi Pengelogan, Pelacakan, dan Metrik, yang terkadang dikenal sebagai pilar pengamatan. Untuk informasi selengkapnya tentang pengamatan integrasi dan telemetri, lihat gambaran umum integrasi .NET.NET Aspire. Bergantung pada layanan pendukung, beberapa integrasi mungkin hanya mendukung beberapa fitur ini. Misalnya, beberapa integrasi mendukung pengelogan dan pelacakan, tetapi bukan metrik. Fitur telemetri juga dapat dinonaktifkan menggunakan teknik yang disajikan di bagian Konfigurasi.

Penebangan

Integrasi .NET Aspire Stack Exchange Redis menggunakan kategori log berikut:

  • Aspire.StackExchange.Redis

Menelusuri

Integrasi .NET AspireRedis Stack Exchange akan memancarkan aktivitas pelacakan berikut menggunakan OpenTelemetry:

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Metrik

Integrasi .NET AspireRedis Stack Exchange saat ini tidak mendukung metrik secara bawaan karena keterbatasan dengan pustaka StackExchange.Redis.

Lihat juga

*: Redis adalah merek dagang terdaftar dari Redis Ltd. Setiap hak di dalamnya dilindungi untuk Redis Ltd. Penggunaan apa pun oleh Microsoft hanya untuk tujuan referensial dan tidak menunjukkan sponsor, dukungan, atau afiliasi apa pun antara Redis dan Microsoft. Kembali keatas?