Orleans ve .NET Aspire entegrasyonu

.NET Aspire , için yerleşik destek Orleansile bulutta yerel uygulamalar oluşturmaya yönelik kolaylaştırılmış bir yaklaşım sağlar. 8.0'dan Orleans başlayarak Kümenizi Orleans düzenlemek, yedekleme kaynaklarını (Redis veya Azure Depolama gibi) yönetmek ve hizmet bulma, gözlemlenebilirlik ve sistem durumu denetimlerini otomatik olarak yapılandırmak için Aspire'i kullanabilirsiniz.

Genel Bakış

.c0 .NET Aspire ile tümleştirme, AppHost projenizde Orleans paketini kullanır. Bu paket aşağıdakiler için uzantı yöntemleri sağlar:

Dağıtılmış kaynak olarak tanımlama Orleans
Kümeleme sağlayıcılarını yapılandırma (Redis, Azure Depolama ADO.NET)
Hububat depolama sağlayıcılarını yapılandırma
Anımsatıcı sağlayıcılarını yapılandırma
Grain dizin sağlayıcılarını yapılandırın
Model silosu ve müşteri ilişkileri

Önkoşullar

Aspire ile Orleans kullanmadan önce aşağıdakilere sahip olduğunuzdan emin olun:

.NET 8.0 SDK veya üzeri
.NET Aspire iş yükü
Aspire desteğine sahip bir IDE (Visual Studio 2022 17.9+, C# Dev Kit ile VS Code veya JetBrains Rider)

Gerekli paketler

Çözümünüz aşağıdaki paket başvurularına ihtiyaç duyar:

AppHost projesi

<ItemGroup>
  <PackageReference Include="Aspire.Hosting.AppHost" Version="9.0.0" />
  <PackageReference Include="Aspire.Hosting.Orleans" Version="9.0.0" />
  <PackageReference Include="Aspire.Hosting.Redis" Version="9.0.0" />
</ItemGroup>

Orleans silo projesi

<ItemGroup>
  <PackageReference Include="Microsoft.Orleans.Server" Version="10.0.0" />
  <PackageReference Include="Microsoft.Orleans.Clustering.Redis" Version="10.0.0" />
  <PackageReference Include="Aspire.StackExchange.Redis" Version="9.0.0" />
</ItemGroup>

Orleans müşteri projesi (silodan ayrıysa)

<ItemGroup>
  <PackageReference Include="Microsoft.Orleans.Client" Version="10.0.0" />
  <PackageReference Include="Microsoft.Orleans.Clustering.Redis" Version="10.0.0" />
  <PackageReference Include="Aspire.StackExchange.Redis" Version="9.0.0" />
</ItemGroup>

AppHost'ı yapılandırma

AppHost projesi kümenizi Orleans ve bağımlılıklarını düzenler.

Redis kümeleme ile temel Orleans küme

public static void BasicOrleansCluster(string[] args)
{
    var builder = DistributedApplication.CreateBuilder(args);

    // Add Redis for Orleans clustering
    var redis = builder.AddRedis("orleans-redis");

    // Define the Orleans resource with Redis clustering
    var orleans = builder.AddOrleans("cluster")
        .WithClustering(redis);

    // Add the Orleans silo project
    builder.AddProject<Projects.Silo>("silo")
        .WithReference(orleans)
        .WaitFor(redis)
        .WithReplicas(3);

    builder.Build().Run();
}

Orleans tahıl depolama ve hatırlatıcılarla

public static void OrleansWithStorageAndReminders(string[] args)
{
    var builder = DistributedApplication.CreateBuilder(args);

    var redis = builder.AddRedis("orleans-redis");

    var orleans = builder.AddOrleans("cluster")
        .WithClustering(redis)
        .WithGrainStorage("Default", redis)
        .WithGrainStorage("PubSubStore", redis)
        .WithReminders(redis);

    builder.AddProject<Projects.Silo>("silo")
        .WithReference(orleans)
        .WaitFor(redis)
        .WithReplicas(3);

    builder.Build().Run();
}

Silo ve istemci projelerini ayırma

İstemciniz Orleans ayrı bir işlemde çalışıyorsa (örneğin, web ön yüzü gibi), .AsClient() metodunu kullanın:

public static void SeparateSiloAndClient(string[] args)
{
    var builder = DistributedApplication.CreateBuilder(args);

    var redis = builder.AddRedis("orleans-redis");

    var orleans = builder.AddOrleans("cluster")
        .WithClustering(redis)
        .WithGrainStorage("Default", redis);

    // Backend Orleans silo cluster
    var silo = builder.AddProject<Projects.Silo>("backend")
        .WithReference(orleans)
        .WaitFor(redis)
        .WithReplicas(5);

    // Frontend web project as Orleans client
    builder.AddProject<Projects.Client>("frontend")
        .WithReference(orleans.AsClient())  // Client-only reference
        .WaitFor(silo);

    builder.Build().Run();
}

Silo projesini Orleans yapılandırma

Silo projenizde Orleans Aspire tarafından sağlanan kaynakları kullanacak şekilde yapılandırın Orleans :

public static void BasicSiloConfiguration(string[] args)
{
    var builder = Host.CreateApplicationBuilder(args);

    // Add Aspire service defaults (OpenTelemetry, health checks, etc.)
    builder.AddServiceDefaults();

    // Add the Aspire Redis client for Orleans
    builder.AddKeyedRedisClient("orleans-redis");

    // Configure Orleans - Aspire injects all configuration automatically
    builder.UseOrleans();

    builder.Build().Run();
}

Tip

.NET Aspire kullanırken, genellikle ihtiyacınız olan tek şey parametresizdir UseOrleans . Aspire, otomatik olarak okunan Orleans ortam değişkenleri aracılığıyla yapılandırma (küme kimliği, hizmet kimliği, uç noktalar ve sağlayıcı ayarları) eklerOrleans. Temsilci aşırı yüklemesine UseOrleans(siloBuilder => {...}) yalnızca Aspire'in sağladığından daha fazla el ile yapılandırmaya ihtiyaç duyduğunuzda ihtiyacınız vardır.

Önemli

Yedek kaynak kaynağını bağımlılık ekleme kapsayıcısına kaydetmek için uygun AddKeyed* yöntemini (gibi AddKeyedRedisClient, AddKeyedAzureTableClient veya AddKeyedAzureBlobClient) çağırmanız gerekir. Orleans sağlayıcılar kaynakları anahtarlı hizmet adlarına göre arar; bu adımı atlarsanız, Orleans kaynağı çözümleyemez ve çalışma zamanında bağımlılık çözümleme hatası oluşturur. Bu, ile Orleanskullanılan tüm Aspire tarafından yönetilen kaynaklar için geçerlidir.

Açık bağlantı dizesiyle yapılandırma

Bağlantı dizesi üzerinde açık denetime ihtiyacınız varsa yapılandırmadan okuyabilirsiniz:

public static void ExplicitConnectionConfiguration(string[] args)
{
    var builder = Host.CreateApplicationBuilder(args);

    builder.AddServiceDefaults();
    builder.AddKeyedRedisClient("orleans-redis");

    builder.UseOrleans(siloBuilder =>
    {
        var redisConnectionString = builder.Configuration.GetConnectionString("orleans-redis");

        siloBuilder.UseRedisClustering(options =>
        {
            options.ConfigurationOptions =
                ConfigurationOptions.Parse(redisConnectionString!);
        });

        siloBuilder.AddRedisGrainStorageAsDefault(options =>
        {
            options.ConfigurationOptions =
                ConfigurationOptions.Parse(redisConnectionString!);
        });
    });

    builder.Build().Run();
}

Orleans İstemci projesini yapılandırın

Ayrı istemci projeleri için istemciyi Orleans benzer şekilde yapılandırın:

public static void BasicClientConfiguration(string[] args)
{
    var builder = Host.CreateApplicationBuilder(args);

    builder.AddServiceDefaults();
    builder.AddKeyedRedisClient("orleans-redis");

    // Configure Orleans client - Aspire injects clustering configuration automatically
    builder.UseOrleansClient();

    builder.Build().Run();
}

AppHost uzantı yöntemleri referansı

Paket şu Aspire.Hosting.Orleans uzantı yöntemlerini sağlar:

Temel yöntemler

Yöntem	Description
`builder.AddOrleans(name)`	Dağıtılmış uygulamaya belirtilen ada sahip bir Orleans kaynak ekler.
`.WithClusterId(id)`	ClusterId değerini Orleans ayarlar. Bir dizeyi veya `ParameterResource` kabul eder. Belirtilmezse, otomatik olarak benzersiz bir kimlik oluşturulur.
`.WithServiceId(id)`	Orleans ServiceId'i ayarlar. Bir dizeyi veya `ParameterResource` kabul eder. Belirtilmezse, otomatik olarak benzersiz bir kimlik oluşturulur.
`.AsClient()`	Yalnızca istemciye özel bir Orleans kaynak için başvuru döndürür (silo yeteneklerini içermez).
`project.WithReference(orleans)`	Bir projeye Orleans kaynak başvurusunu ekler ve yapılandırma enjeksiyonunu etkinleştirir.

Uyarı

, .WithClustering(resource)veya benzer yöntemler kullanarak .WithGrainStorage(name, resource)bir yedekleme kaynağı yapılandırdığınızda, Orleans kaynak otomatik olarak bu yedekleme kaynağına bir başvuru ekler. Her bir yedekleme kaynağı için ayrı ayrı arama .WithReference() yapmanız gerekmez; yalnızca .WithReference(orleans) gereklidir. Ancak, silo başlamadan önce hazır olduğundan emin olmak için .WaitFor() yedekleme kaynağını kullanmanız gerekir.

Clustering

Yöntem	Description
`.WithClustering(resource)`	Orleans Kümelemeye belirtilen kaynağı (Redis, Azure Depolama, Cosmos DB vb.) kullanacak şekilde yapılandırılır.
`.WithDevelopmentClustering()`	Yalnızca yerel geliştirme için, bellek içi ve tek konaklı kümeleme yapılandırmasını düzenler. Üretim için uygun değildir.

Tahıl depolama

Yöntem	Description
`.WithGrainStorage(name, resource)`	Belirtilen kaynağı kullanarak adlandırılmış bir grain depolama sağlayıcısını yapılandırır.
`.WithMemoryGrainStorage(name)`	Belirtilen ad için bellek içi tanecik depolamayı yapılandırıyor. Silo yeniden başlatıldığında veriler kaybolur.

Hatırlatmalar

Yöntem	Description
`.WithReminders(resource)`	Belirtilen kaynağı kullanarak anımsatıcı hizmetini yapılandırıyor Orleans .
`.WithMemoryReminders()`	Geliştirme için bellek içi anımsatıcılar yapılandırılır. Silo yeniden başlatıldığında anımsatıcılar kaybolur.

Yayın

Yöntem	Description
`.WithStreaming(name, resource)`	Belirtilen kaynağı (örneğin, Azure Kuyruk Depolama) kullanarak adlandırılmış bir akış sağlayıcısı yapılandırılır.
`.WithMemoryStreaming(name)`	Geliştirme amacıyla bellek içi akış yapılandırması yapılır.
`.WithBroadcastChannel(name)`	Belirtilen adlı bir yayın kanalı sağlayıcısı yapılandırılır.

Grain rehberi

Yöntem	Description
`.WithGrainDirectory(name, resource)`	Belirtilen kaynağı kullanarak adlandırılmış bir grain dizini yapılandır.

Hizmet varsayılanları şablonu

Aspire, ortak yapılandırmayı tüm projelerde paylaşmak için ServiceDefaults proje deseni kullanır. için Orleansbu genellikle şunları içerir:

OpenTelemetry yapılandırması

public static IHostApplicationBuilder AddServiceDefaults(
    this IHostApplicationBuilder builder)
{
    builder.ConfigureOpenTelemetry();
    builder.AddDefaultHealthChecks();
    
    return builder;
}

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");  // Orleans metrics
        })
        .WithTracing(tracing =>
        {
            tracing.AddAspNetCoreInstrumentation()
                .AddHttpClientInstrumentation()
                .AddSource("Microsoft.Orleans.Runtime")
                .AddSource("Microsoft.Orleans.Application");
        });

    return builder;
}

Aspire ile Azure Depolama

Kümeleme ve kalıcılık için Orleans Azure Depolama kaynaklarını kullanabilirsiniz:

public static void AzureStorageWithAspire(string[] args)
{
    var builder = DistributedApplication.CreateBuilder(args);

    // Add Azure Storage for Orleans
    var storage = builder.AddAzureStorage("orleans-storage")
        .RunAsEmulator();  // Use Azurite emulator for local development

    var tables = storage.AddTables("orleans-tables");
    var blobs = storage.AddBlobs("orleans-blobs");

    var orleans = builder.AddOrleans("cluster")
        .WithClustering(tables)
        .WithGrainStorage("Default", blobs)
        .WithReminders(tables);

    builder.AddProject<Projects.Silo>("silo")
        .WithReference(orleans)
        .WaitFor(storage)
        .WithReplicas(3);

    builder.Build().Run();
}

Geliştirme ve üretim yapılandırması karşılaştırması

Aspire, geliştirme ve üretim yapılandırmaları arasında geçiş yapmanızı kolaylaştırır:

Yerel geliştirme (emülatörleri kullanarak)

public static void LocalDevelopment(string[] args)
{
    var builder = DistributedApplication.CreateBuilder(args);

    var redis = builder.AddRedis("orleans-redis");
    // Redis container runs automatically during development

    var orleans = builder.AddOrleans("cluster")
        .WithClustering(redis);

    // ...
}

Üretim (yönetilen hizmetleri kullanarak)

public static void ProductionConfig(string[] args)
{
    var builder = DistributedApplication.CreateBuilder(args);

    // Use existing Azure Cache for Redis
    var redis = builder.AddConnectionString("orleans-redis");

    var orleans = builder.AddOrleans("cluster")
        .WithClustering(redis);

    // ...
}

Sağlık kontrolleri

Aspire, sistem durumu denetimi uç noktalarını otomatik olarak yapılandırıyor. Özel Orleans-sağlık kontrolleri ekleyebilirsiniz.

public static void ConfigureHealthChecks(IHostApplicationBuilder builder)
{
    builder.Services.AddHealthChecks()
        .AddCheck<GrainHealthCheck>("orleans-grains")
        .AddCheck<SiloHealthCheck>("orleans-silo");
}

En iyi yöntemler

ServiceDefaults kullanma: ServiceDefaults projesini kullanarak tüm projelerde ortak yapılandırmayı (OpenTelemetry, sistem durumu denetimleri) paylaşın.
Bağımlılıkları bekleyin: .WaitFor() her zaman silolar başlamadan önce destek kaynaklarının (Redis, veritabanları) hazır olduğundan emin olmak için kullanınOrleans.
Çoğaltmaları yapılandırma: Hataya dayanıklılık ve ölçeklenebilirlik için birden fazla silo örneği çalıştırmak amacıyla .WithReplicas() kullanın.
Ayrı istemci projeleri: Web ön uçlarında yalnızca istemci modunu yapılandırmak için .AsClient()Orleans kullanın.
Geliştirme için öykünücüleri kullanma: Aspire, Redis, Azure Depolama (Azurite) ve diğer bağımlılıkları kapsayıcılar kullanarak yerel bir ortamda çalıştırabilir.
Dağıtılmış izlemeyi etkinleştirme: Küme genelindeki grain çağrılarını izlemek için Orleans kaynak adlarıyla OpenTelemetry'yi yapılandırın.

Ayrıca bakınız

.NET Aspire tümleştirmesi 8.0'da Orleans kullanıma sunulmuştur. Orleans 7.0 için Aspire tarafından düzenlenen ortamlara dağıtmaya devam edebilirsiniz, ancak özel Aspire.Hosting.Orleans paketi ve uzantı metotları kullanılamaz.

Aspire tümleştirme özelliklerinden yararlanmak için Orleans 8.0 veya sonraki bir sürüme yükseltmeyi göz önünde bulundurun.

.NET Aspire tümleştirmesi 8.0 ve üzeri sürümlerde Orleans kullanılabilir. Orleans 3.x, .NET Aspire'i desteklemez.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-01-23