integrasi .NET AspireOrleans

Orleans memiliki dukungan bawaan untuk .NET.NET Aspire. model aplikasi .NET.NET Aspirememungkinkan Anda menjelaskan layanan, database, dan sumber daya dan infrastruktur lainnya di aplikasi Anda dan bagaimana mereka berhubungan satu sama lain. Orleans menyediakan cara mudah untuk membangun aplikasi terdistribusi yang dapat diskalakan secara elastis dan toleran terhadap kesalahan. Anda dapat menggunakan .NET Aspire untuk mengonfigurasi dan mengatur Orleans dan dependensinya, seperti dengan menyediakan Orleans dengan keanggotaan dan penyimpanan kluster.

Orleans direpresentasikan sebagai sumber daya dalam .NET Aspire. Tidak seperti integrasi lain, integrasi Orleans tidak membuat kontainer dan tidak memerlukan paket integrasi klien terpisah. Sebagai gantinya, Anda menyelesaikan konfigurasi Orleans di proyek host aplikasi .NET Aspire.

Integrasi hosting

Integrasi hosting Orleans memodelkan layanan Orleans sebagai jenis OrleansService. Untuk mengakses jenis dan API ini, tambahkan paket NuGet 📦Aspire.Hosting.Orleans dalam proyek host aplikasi .

dotnet add package Aspire.Hosting.Orleans

<PackageReference Include="Aspire.Hosting.Orleans"
                  Version="*" />

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

Menambahkan sumber daya Orleans

Di proyek host aplikasi Anda, panggil AddOrleans untuk menambahkan dan mengembalikan builder layanan sumber daya Orleans. Nama yang diberikan ke sumber daya Orleans adalah untuk tujuan diagnostik. Untuk sebagian besar aplikasi, nilai "default" cukup.

var orleans = builder.AddOrleans("default")

Menggunakan penyimpanan Azure untuk pengklusteran tabel dan penyimpanan biji-bijian

Dalam aplikasi Orleans, blok penyusun dasar adalah unit . Biji-bijian dapat memiliki status tahan lama. Anda harus menyimpan keadaan tahan lama untuk biji-bijian di suatu tempat. Dalam aplikasi .NET.NET Aspire, Azure Blob Storage adalah salah satu lokasi yang mungkin.

Orleans host mendaftarkan diri mereka dalam database dan menggunakan database tersebut untuk saling menemukan dan membentuk kluster. Mereka menyimpan server mana yang merupakan anggota silo mana dalam tabel database. Anda dapat menggunakan database relasional atau NoSQL untuk menyimpan informasi ini. Dalam aplikasi .NET.NET Aspire, pilihan populer untuk menyimpan tabel ini Azure Table Storage.

Untuk mengonfigurasi Orleans dengan pengklusteran dan penyimpanan gandum di Azure, instal paket NuGet 📦Aspire.Hosting.Azure.Storage dalam proyek host aplikasi:

dotnet add package Aspire.Hosting.Azure.Storage

<PackageReference Include="Aspire.Hosting.Azure.Storage"
                  Version="*" />

Dalam proyek host aplikasi Anda, setelah Anda memanggil AddOrleans, konfigurasikan sumber daya Orleans dengan pengklusteran dan penyimpanan data menggunakan metode WithClustering dan WithGrainStorage masing-masing.

// Add the resources which you will use for Orleans clustering and
// grain state storage.
var storage = builder.AddAzureStorage("storage").RunAsEmulator();
var clusteringTable = storage.AddTables("clustering");
var grainStorage = storage.AddBlobs("grain-state");

// Add the Orleans resource to the Aspire DistributedApplication
// builder, then configure it with Azure Table Storage for clustering
// and Azure Blob Storage for grain storage.
var orleans = builder.AddOrleans("default")
                     .WithClustering(clusteringTable)
                     .WithGrainStorage("Default", grainStorage);

Kode sebelumnya memberi tahu Orleans bahwa layanan apa pun yang mereferensikannya juga harus mereferensikan sumber daya clusteringTable.

Menambahkan proyek server Orleans di host aplikasi

Sekarang Anda dapat menambahkan proyek baru yang terdaftar dalam orkestrasi .NET Aspire ke solusi Anda sebagai server Orleans. Ini akan mengambil bagian dalam kluster Orleans sebagai silo dengan butir konstituen. Referensikan sumber daya Orleans dari proyek server Anda menggunakan WithReference(orleans). Saat Anda mereferensikan sumber daya Orleans dari layanan Anda, sumber daya tersebut juga dirujuk:

// Add your server project and reference your 'orleans' resource from it.
// It can join the Orleans cluster as a silo.
// This implicitly adds references to the required resources.
// In this case, that is the 'clusteringTable' resource declared earlier.
builder.AddProject<Projects.OrleansServer>("silo")
       .WithReference(orleans)
       .WithReplicas(3);

Menambahkan proyek klien Orleans di host aplikasi

Orleans klien berkomunikasi dengan biji-bijian yang dihosting di server Orleans. Di aplikasi .NET Aspire, misalnya, Anda mungkin memiliki situs Web front-end yang memanggil butiran dalam kluster Orleans. Referensikan sumber daya Orleans dari klien Orleans Anda menggunakan WithReference(orleans.AsClient()).

// Reference the Orleans resource as a client from the 'frontend'
// project so that it can connect to the Orleans cluster.
builder.AddProject<Projects.OrleansClient>("frontend")
       .WithReference(orleans.AsClient())
       .WithExternalHttpEndpoints()
       .WithReplicas(3);

Membuat proyek server Orleans

Setelah proyek host aplikasi selesai, Anda dapat menerapkan proyek server Orleans. Mari kita mulai dengan menambahkan paket NuGet yang diperlukan:

dotnet add package Aspire.Azure.Data.Tables
dotnet add package Aspire.Azure.Storage.Blobs
dotnet add package Microsoft.Orleans.Server
dotnet add package Microsoft.Orleans.Persistence.AzureStorage
dotnet add package Microsoft.Orleans.Clustering.AzureStorage

<PackageReference Include="Aspire.Azure.Data.Tables"
                  Version="*" />
<PackageReference Include="Aspire.Azure.Storage.Blobs"
                  Version="*" />
<PackageReference Include="Microsoft.Orleans.Persistence.AzureStorage"
                  Version="*" />
<PackageReference Include="Microsoft.Orleans.Clustering.AzureStorage"
                  Version="*" />

Selanjutnya, dalam file Program.cs proyek server Orleans Anda, tambahkan klien blob dan tabel Azure Storage lalu panggil UseOrleans.

var builder = WebApplication.CreateBuilder(args);

builder.AddServiceDefaults();
builder.AddKeyedAzureTableClient("clustering");
builder.AddKeyedAzureBlobClient("grain-state");
builder.UseOrleans();

Kode berikut adalah contoh lengkap proyek server Orleans, termasuk butir bernama CounterGrain:

using Orleans.Runtime;
using OrleansContracts;

var builder = WebApplication.CreateBuilder(args);

builder.AddServiceDefaults();
builder.AddKeyedAzureTableClient("clustering");
builder.AddKeyedAzureBlobClient("grain-state");
builder.UseOrleans();

var app = builder.Build();

app.MapGet("/", () => "OK");

await app.RunAsync();

public sealed class CounterGrain(
    [PersistentState("count")] IPersistentState<int> count) : ICounterGrain
{
    public ValueTask<int> Get()
    {
        return ValueTask.FromResult(count.State);
    }

    public async ValueTask<int> Increment()
    {
        var result = ++count.State;
        await count.WriteStateAsync();
        return result;
    }
}

Buatlah proyek untuk klien Orleans

Dalam proyek klien Orleans, tambahkan paket NuGet yang sama:

dotnet add package Aspire.Azure.Data.Tables
dotnet add package Aspire.Azure.Storage.Blobs
dotnet add package Microsoft.Orleans.Client
dotnet add package Microsoft.Orleans.Persistence.AzureStorage
dotnet add package Microsoft.Orleans.Clustering.AzureStorage

<PackageReference Include="Aspire.Azure.Data.Tables"
                  Version="*" />
<PackageReference Include="Aspire.Azure.Storage.Blobs"
                  Version="*" />
<PackageReference Include="Microsoft.Orleans.Persistence.AzureStorage"
                  Version="*" />
<PackageReference Include="Microsoft.Orleans.Clustering.AzureStorage"
                  Version="*" />

Selanjutnya, dalam file Program.cs proyek klien Orleans Anda, tambahkan klien penyimpanan tabel Azure lalu panggil UseOrleansClient.

builder.AddKeyedAzureTableClient("clustering");
builder.UseOrleansClient();

Kode berikut adalah contoh lengkap proyek klien Orleans. Ini memanggil butir CounterGrain yang ditentukan dalam contoh server Orleans di atas:

using OrleansContracts;

var builder = WebApplication.CreateBuilder(args);

builder.AddServiceDefaults();
builder.AddKeyedAzureTableClient("clustering");
builder.UseOrleansClient();

var app = builder.Build();

app.MapGet("/counter/{grainId}", async (IClusterClient client, string grainId) =>
{
    var grain = client.GetGrain<ICounterGrain>(grainId);
    return await grain.Get();
});

app.MapPost("/counter/{grainId}", async (IClusterClient client, string grainId) =>
{
    var grain = client.GetGrain<ICounterGrain>(grainId);
    return await grain.Increment();
});

app.UseFileServer();

await app.RunAsync();

Mengaktifkan OpenTelemetry

Berdasarkan konvensi, solusi .NET.NET Aspire mencakup proyek untuk menentukan konfigurasi dan perilaku default untuk layanan Anda. Proyek ini disebut default layanan proyek dan templat membuatnya dengan nama yang berakhiran ServiceDefaults. Untuk mengonfigurasi Orleans untuk OpenTelemetry di .NET Aspire, terapkan pengaturan ke proyek default layanan Anda dengan mengikuti panduan pengamatan Orleans.

Ubah metode ConfigureOpenTelemetry untuk menambahkan Orleansmeter dan instrumen pelacakan . Cuplikan kode berikut menunjukkan file Extensions.cs yang dimodifikasi dari proyek default layanan yang menyertakan metrik dan jejak dari Orleans.

public static IHostApplicationBuilder ConfigureOpenTelemetry(this IHostApplicationBuilder builder)
{
    builder.Logging.AddOpenTelemetry(logging =>
    {
        logging.IncludeFormattedMessage = true;
        logging.IncludeScopes = true;
    });

    builder.Services.AddOpenTelemetry()
        .WithMetrics(metrics =>
        {
            metrics.AddAspNetCoreInstrumentation()
                .AddHttpClientInstrumentation()
                .AddRuntimeInstrumentation()
                .AddMeter("Microsoft.Orleans");
        })
        .WithTracing(tracing =>
        {
            tracing.AddSource("Microsoft.Orleans.Runtime");
            tracing.AddSource("Microsoft.Orleans.Application");

            tracing.AddAspNetCoreInstrumentation()
                .AddHttpClientInstrumentation();
        });

    builder.AddOpenTelemetryExporters();

    return builder;
}

Penyedia yang didukung

Integrasi OrleansAspire mendukung subset terbatas penyedia Orleans saat ini:

• Clustering:
  • Redis
  • Tabel Penyimpanan Azure
• Ketekunan:
  • Redis
  • Tabel Penyimpanan Azure
  • Azure Penyimpanan Blob
• Pengingat:
  • Redis
  • Tabel Penyimpanan Azure
• Direktori biji-bijian:
  • Redis
  • Tabel Penyimpanan Azure

Penyedia streaming tidak didukung pada Orleans versi 8.1.0.

Langkah berikutnya