.NET Aspire Orleans tümleştirmesi

Orleans .NET .NET Aspireiçin yerleşik desteğe sahiptir. .NET .NET Aspireuygulama modeli, uygulamanızdaki hizmetleri, veritabanlarını ve diğer kaynakları ve altyapıyı ve bunların birbirleriyle ilişkisini açıklamanıza olanak tanır. Orleans esnek bir şekilde ölçeklenebilir ve hataya dayanıklı dağıtılmış uygulamalar oluşturmak için basit bir yol sağlar. .NET Aspire kullanarak Orleans ve bağımlılıklarını yapılandırabilir ve düzenleyebilirsiniz; örneğin küme üyeliği ve depolama ile Orleans sağlayabilirsiniz.

Orleans, .NET Aspireiçinde bir kaynak olarak temsil edilir. Diğer tümleştirmelerden farklı olarak, Orleans tümleştirmesi bir kapsayıcı oluşturmaz ve ayrı bir client tümleştirme paketi gerektirmez. Bunun yerine .NET Aspire host uygulama projesinde Orleans yapılandırmasını tamamlarsınız.

Barındırma entegrasyonu

Orleans barındırma tümleştirmesi, bir Orleans hizmetini OrleansService türü olarak modeller. Bu tür ve API'lere erişim sağlamak için 📦Aspire.Hosting.Orleans NuGet paketini uygulama konağı projesine ekleyin.

dotnet add package Aspire.Hosting.Orleans

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

Daha fazla bilgi için bkz. dotnet add package veya .NET uygulamalarında paket bağımlılıklarını yönetme.

Orleans kaynağı ekleme

Uygulama ana bilgisayar projenizde, Orleans hizmeti kaynak oluşturucusu eklemek ve döndürmek için AddOrleans çağırabilirsiniz. Orleans kaynağına sağlanan ad tanılama amacıyla kullanılır. Çoğu uygulama için "default" değeri yeterlidir.

var orleans = builder.AddOrleans("default")

Tabloları kümeleme ve tane depolamayı için Azure depolamayı kullanın

Orleans uygulamasında, temel yapı taşı birim'dir. Tahıllar dayanıklı durumlara sahip olabilir. Bir tahıl için dayanıklı durumu bir yerde depolamanız gerekir. .NET .NET Aspire bir uygulamada, Azure Blob Storage olası bir konumdur.

Orleans konaklar kendilerini bir veritabanına kaydeder ve birbirlerini bulmak ve küme oluşturmak için bu veritabanını kullanır. Veritabanı tablosunda hangi sunucuların üyesi olduğu siloları depolar. Bu bilgileri depolamak için ilişkisel veya NoSQL veritabanlarını kullanabilirsiniz. .NET .NET Aspire bir uygulamada, bu tabloyu depolamak için popüler bir seçenek Azure Table Storage.

Azure'de kümelenme ve tanecik depolama ile Orleans'ı yapılandırmak için, uygulama ana bilgisayar projesinde 📦AspireHostingAzureDepolama NuGet paketini yükleyin.

dotnet add package Aspire.Hosting.Azure.Storage

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

Uygulama ana bilgisayar projenizde, AddOrleansçağrısı yaptıktan sonra sırasıyla WithClustering ve WithGrainStorage yöntemlerini kullanarak kümeleme ve tahıl depolama ile Orleans kaynağını yapılandırın:

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

Önceki kod, Orleans'a başvuran herhangi bir hizmetin de clusteringTable kaynağına başvurması gerektiğini belirtir.

Uygulama konağına Orleansserver proje ekleme

Artık, .NET Aspire düzenlemesine kaydedilen yeni bir projeyi, çözümünüze Orleansserverolarak ekleyebilirsiniz. Orleans kümesinde, bileşen tanecikleri içeren bir silo olarak yer alır. WithReference(orleans)kullanarak server projenizdeki Orleans kaynağına başvurun. Hizmetinizden Orleans kaynağına referans verdiğinizde, şu kaynaklara da referans verilir:

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

Uygulama konağına Orleansclient proje ekleme

Orleans istemcileri Orleans sunucularda barındırılan taneciklerle iletişim kurar. Örneğin .NET Aspire bir uygulamada, Orleans kümesindeki tanecikleri çağıran bir ön uç Web siteniz olabilir. Orleans client kullanarak WithReference(orleans.AsClient())ile Orleans kaynağına başvurun.

// 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 server projesini oluşturma

Artık uygulama konak projesi tamamlandı, Orleansserver projesini uygulayabilirsiniz. Gerekli NuGet paketlerini ekleyerek başlayalım:

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="*" />

Ardından, Orleansserver projenizin Program.cs dosyasına Azure Depolama blobu ve tablo istemcilerini ekleyin ve ardından UseOrleansçağrısı yapın.

var builder = WebApplication.CreateBuilder(args);

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

Aşağıdaki kod, CounterGrainadlı bir tanecik de dahil olmak üzere bir Orleansserver projesinin tam bir örneğidir:

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 client projesi oluşturma

Orleans client projesinde aynı NuGet paketlerini ekleyin:

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="*" />

Ardından, Orleansclient projenizin Program.cs dosyasında Azure tablo depolama client ekleyin ve ardından UseOrleansClientçağrısı yapın.

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

Aşağıdaki kod, Orleansclient projesinin tam bir örneğidir. Yukarıdaki Orleansserver örnekte tanımlanan CounterGrain dilimini çağırır:

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 etkinleştirme

Kurala göre .NET.NET Aspire çözümler, hizmetiniz için varsayılan yapılandırmayı ve davranışı tanımlamaya yönelik bir proje içerir. Bu projeye hizmeti varsayılanları proje adı verilen ve şablonlar, ServiceDefaultsile biten bir adla bunu oluşturur. .NET Aspire'da OpenTelemetry için Orleans yapılandırmak için, Orleans gözlemlenebilirlik kılavuzunu izleyerek yapılandırmayı hizmet varsayılanları projenize uygulayın.

yöntemini, ölçüm cihazlarını ve izleyecek araçlarını ekleyerek değiştirin. Aşağıdaki kod parçacığı, ölçümlerini ve izlemelerini içeren bir hizmet varsayılanları projesinden değiştirilmiş Orleans dosyasını gösterir.

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

Desteklenen sağlayıcılar

Orleans Aspire tümleştirmesi bugün Orleans sağlayıcılarının sınırlı bir alt kümesini destekler:

• Kümeleme:
  • Redis
  • Azure Depolama Tabloları
• Devamlılık:
  • Redis
  • Azure Depolama Tabloları
  • Azure Depolama Blobları
• Hatırlatmalar:
  • Redis
  • Azure Depolama Tabloları
• Tahıl rehberi
  • Redis
  • Azure Depolama Tabloları

Akış sağlayıcıları, Orleans sürüm 8.1.0 itibarıyla desteklenmez.

Sonraki adımlar