使用 Orleans 搭配 .NET Aspire

發行項
12/14/2024

Orleans 內建支持 .NET Aspire。 .NET .NET Aspire的應用程式模型可讓您描述應用程式中的服務、資料庫和其他資源/基礎結構及其關聯方式。 Orleans 提供簡單的方法來建置可彈性調整和容錯的分散式應用程式。 .NET Aspire 可用來設定及協調 Orleans 及其相依性，例如藉由提供 Orleans 資料庫叢集成員資格和儲存空間。

Orleans 是以 .NET Aspire中的資源表示。 Orleans 資源包含您的服務需要運作的設定，例如叢集成員資格提供者和記憶體提供者。

先決條件

若要使用 .NET.NET Aspire，您需要在本機安裝下列項目：

.NET 8.0 或 .NET 9.0
符合 OCI 規範的容器運行時間，例如：
- Docker 桌面或 Podman。如需詳細資訊，請參閱容器運行時間。
整合式開發人員環境（IDE）或程式碼編輯器，例如：
- Visual Studio 2022 17.9 版或更高版本（選用）
- Visual Studio Code （選擇性）
  - C# Dev Kit：擴充功能（選擇性）
- JetBrains Rider 搭配 .NET.NET Aspire 外掛程式（選用）

如需詳細資訊，請參閱 .NET.NET Aspire 設定和工具和 .NET.NET Aspire SDK。

除了 .NET.NET Aspire的必要條件之外，您還需要：

Orleans 8.1.0 版或更新版本

如需詳細資訊，請參閱 .NET.NET Aspire 安裝和工具。

開始

若要開始使用，您必須安裝 Orleans NuGet 套件，將裝載套件新增至您的應用程式主機專案。

.NET 命令列介面
PackageReference

dotnet add package Aspire.Hosting.Orleans

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

如需詳細資訊，請參閱 dotnet add package 或在 .NET 應用程式中管理套件相依性。

Orleans 資源使用 .NET Aspire 方法新增至 AddOrleans(string name) 分散式應用程式產生器，該方法會傳回一個 Orleans 資源產生器。提供給 Orleans 資源的名稱僅供診斷之用。對大多數應用程式而言，"default" 值就已足夠。

var orleans = builder.AddOrleans("default")

Orleans 資源產生器提供方法來設定 Orleans 資源。

若要將 Orleans 設定為叢集和 grain 儲存，請在應用程式主機專案中安裝 📦Aspire.Hosting.Azure.Storage NuGet 套件。

.NET 命令列介面
PackageReference

dotnet add package Aspire.Hosting.Azure.Storage

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

在下列範例中，Orleans 資源會分別使用 WithClustering 和 WithGrainStorage 方法來設定叢集和糧食儲存：

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

上述程式代碼會告訴 Orleans，任何參考它的服務也需要參考 clusteringTable 資源。

若要參與 Orleans 叢集，從您的服務項目參考 Orleans 資源，可以使用 WithReference(orleans) 參與作為 Orleansserver，或使用 WithReference(orleans.AsClient()) 參與作為 client。當您從服務中參考 Orleans 資源時，也會同時參考相關的其他資源。

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

綜合以上內容，以下是 .NET.NET Aspire 應用程式主機專案的一個範例，其中包括：

具有叢集和記憶體的 Orleans 資源。
Orleans server 專案，OrleansServer。
Orleans client 專案，OrleansClient。

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

// Build and run the application.
using var app = builder.Build();
await app.RunAsync();

若要從 .NET AspireOrleans 專案中取用 Orleansserver 資源，有一些步驟：

新增相關的 .NET.NET Aspire 集成。在這裡範例中，您會使用 Aspire.Azure.Data.Tables 和 Aspire.Azure.Storage.Blobs。
新增 Orleans 提供者套件以支持那些 .NET Aspire 集成。在這裡範例中，您會使用 Microsoft.Orleans.Persistence.AzureStorage 和 Microsoft.Orleans.Clustering.AzureStorage。
將 Orleans 新增至主應用程式產生器。

在 Program.csOrleans 項目的 server 檔案中，您必須設定所使用的 .NET Aspire 整合，並將 Orleans 新增至主機產生器。提供的名稱必須符合 .NET.NET Aspire 應用程式主機專案中所使用的名稱：叢集提供者的「叢集」，以及糧食狀態儲存提供者的「粒狀狀態」：

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

您需要在 OrleansClient 專案中執行類似的操作，新增專案所需的 .NET Aspire 資源，以便作為 Orleans加入 client 叢集，並設定主機生成器以新增 Orleansclient：

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

啟用 OpenTelemetry

依照慣例，.NET.NET Aspire 解決方案包含專案，以定義服務的預設組態和行為。此項目稱為 服務預設 專案，且範本會建立名稱結尾為 ServiceDefaults。若要在 Orleans中設定 OpenTelemetry 的 .NET Aspire，您必須依照的Orleans 可觀察性指南，將設定套用至您的服務預設值專案。簡言之，您需要修改 ConfigureOpenTelemetry 方法，以新增 Orleans計量和追蹤儀器。下列代碼段顯示來自服務預設專案的修改 Extensions.cs 檔案，其中包含來自 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;
}

支援的提供者

Orleans Aspire 整合目前支援一些有限的 Orleans 提供者。

聚類：
- Redis
- Azure 記憶體數據表
堅持：
- Redis
- Azure 記憶體數據表
- Azure 儲存 Blob
提醒：
- Redis
- Azure 記憶體數據表
穀物目錄：
- Redis
- Azure 記憶體數據表

從 Orleans 版 8.1.0 開始，不再支持串流提供者。

後續步驟

探索 Orleans 投票範例應用程式

共用方式為

使用 Orleans 搭配 .NET Aspire

先決條件

開始

啟用 OpenTelemetry

支援的提供者

後續步驟

其他資源