共用方式為

.NET Aspire Orleans 整合

  • 發行項

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

Orleans 是以 .NET Aspire中的資源表示。 不同於其他整合，Orleans 整合不會建立容器，而且不需要個別的用戶端整合套件。 相反地，您會在 Orleans 應用程式主機專案中完成 .NET Aspire 設定。

注意

此整合需要 Orleans 8.1.0 版或更新版本。

主機整合

Orleans 的託管整合將 Orleans 服務模型轉化為 OrleansService 類型。 若要存取此類型和 API，請在 📦 專案中新增 AspireOrleans.Hosting. NuGet 套件。

dotnet add package Aspire.Hosting.Orleans

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

新增 Orleans 資源

在您的應用程式主專案中，呼叫 AddOrleans 以新增和傳回 Orleans 服務資源產生器。 提供給 Orleans 資源的名稱僅供診斷之用。 對大多數應用程式而言，"default" 值就已足夠。

var orleans = builder.AddOrleans("default")

使用 Azure 記憶體來叢集數據表和穀物儲存

在 Orleans 應用程式中，基本建置組塊是 粒紋。 穀物可以保持耐久性。 您必須將穀物的持久狀態儲存在某處。 在 .NET.NET Aspire 應用程式中，Azure Blob Storage 是一個可能的位置。

Orleans 主機會在資料庫中註冊自己，並使用該資料庫來尋找彼此並形成叢集。 他們在資料庫表中儲存哪些伺服器是哪些資料倉的成員。 您可以使用關係資料庫或 NoSQL 資料庫來儲存此資訊。 在 .NET.NET Aspire 應用程式中，儲存此數據表的熱門選擇是 Azure Table Storage。

若要在 Orleans中使用叢集和資料存儲來設定 Azure，請在應用程式宿主專案中安裝 📦Aspire主控Azure存儲 NuGet 套件。

dotnet add package Aspire.Hosting.Azure.Storage

在應用程式主機專案中，呼叫 AddOrleans之後，請使用 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 伺服器專案

現在，您可以在 .NET Aspire 協作環境中新增一個新專案，並將其作為 Orleans 伺服器加入您的解決方案。 它將作為一個包含組成顆粒的筒倉參加 Orleans 叢集。 使用 WithReference(orleans)，從您的伺服器項目參考 Orleans 資源。 當您從服務中參考 Orleans 資源時，也會同時參考相關的其他資源。

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

在應用程式主機中新增 Orleans 客戶端專案

Orleans 客戶端會與裝載在 Orleans 伺服器上的 Grain 通訊。 例如，在 .NET Aspire 應用程式中，您可能會有一個前端網站，它會在 Orleans 叢集中呼叫粒紋。 使用 WithReference(orleans.AsClient())，從 Orleans 客戶端參考 Orleans 資源。

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

建立 Orleans 伺服器專案

現在應用程式主專案已完成，您可以實作 Orleans 伺服器專案。 讓我們從新增必要的 NuGet 套件開始：

在 Orleans 伺服器項目的資料夾中，執行下列命令：

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

接下來，在 Orleans 伺服器項目的 Program.cs 檔案中，新增 Azure 記憶體 Blob 和資料表客戶端，然後呼叫 UseOrleans。

var builder = WebApplication.CreateBuilder(args);

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

下列程式代碼是 Orleans 伺服器專案的完整範例，包括名為 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;
    }
}

建立 Orleans 客戶端專案

在 Orleans 客戶端專案中，新增相同的 NuGet 套件：

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

接下來，在 Orleans 客戶端專案的 Program.cs 檔案中，新增 Azure 資料表記憶體客戶端，然後呼叫 UseOrleansClient。

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

下列程式代碼是 Orleans 客戶端專案的完整範例。 它會呼叫上述 Orleans 伺服器範例中定義的 CounterGrain 粒紋：

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 開始，不再支持串流提供者。

後續步驟

Microsoft Orleans 文件探索 Orleans 投票範例應用程式