Orleans und .NET Aspire-Integration

.NET Aspire bietet einen optimierten Ansatz zum Erstellen von cloudeigenen Anwendungen mit integrierter Unterstützung für Orleans. Orleans Ab 8.0 können Sie Ihren Cluster mithilfe von Aspire koordinierenOrleans, Sicherungsressourcen (z. B. Redis oder Azure Storage) verwalten und Dienstermittlung, Observability und Integritätsprüfungen automatisch konfigurieren.

Überblick

.NET Aspire-Integration mit Orleans verwendet das Aspire.Hosting.Orleans-Paket in Ihrem AppHost-Projekt. Dieses Paket bietet Erweiterungsmethoden für:

• Definieren Orleans als verteilte Ressource
• Konfigurieren von Clusteringanbietern (Redis, Azure Storage, ADO.NET)
• Konfigurieren von Getreidespeicheranbietern
• Konfigurieren von Erinnerungsanbietern
• Konfigurieren von Kornverzeichnisanbietern
• Modellsilos und Kundenbeziehungen

Voraussetzungen

Stellen Sie vor der Verwendung von Orleans mit Aspire sicher, dass Sie Folgendes haben:

• .NET 8.0 SDK oder höher
• .NET Aspire Workload
• Eine IDE mit Aspire-Unterstützung (Visual Studio 2022 17.9+, VS Code mit C# Dev Kit oder JetBrains Rider)

Erforderliche Pakete

Ihre Lösung benötigt die folgenden Paketverweise:

AppHost-Projekt

<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 Siloprojekt

<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 Kundenprojekt (falls getrennt vom Silo)

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

Konfigurieren des AppHost

Das AppHost-Projekt koordiniert Ihren Orleans Cluster und seine Abhängigkeiten.

Einfacher Orleans Cluster mit Redis-Clustering

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 mit Getreidespeicherung und Erinnerungen

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

Getrennte Silo- und Clientprojekte

Wenn Ihr Orleans Client in einem separaten Prozess (z. B. einem Web-Frontend) ausgeführt wird, verwenden Sie die .AsClient() Methode:

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

Konfigurieren des Siloprojekts Orleans

Konfigurieren Sie in Ihrem Orleans Siloprojekt Orleans so, dass die von Aspire bereitgestellten Ressourcen verwendet werden:

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

Tipp

Bei der Verwendung von .NET Aspire ist die Parameterlosigkeit UseOrleans in der Regel alles, was Sie benötigen. Aspire fügt Konfiguration (Cluster-ID, Dienst-ID, Endpunkte und Anbietereinstellungen) über Umgebungsvariablen Orleans ein, die Orleans automatisch gelesen werden. Sie benötigen die Delegatüberladung UseOrleans(siloBuilder => {...}) nur, wenn eine zusätzliche manuelle Konfiguration erforderlich ist, die über das hinausgeht, was Aspire zur Verfügung stellt.

Von Bedeutung

Sie müssen die entsprechende AddKeyed*-Methode (z. B. AddKeyedRedisClient, AddKeyedAzureTableClient oder AddKeyedAzureBlobClient) aufrufen, um die Sicherungsressource im Dependency-Injection-Container zu registrieren. Orleans Anbieter suchen Ressourcen anhand ihres Schlüsseldienstnamens – wenn Sie diesen Schritt überspringen, kann Orleans die Ressource nicht auflösen und löst zur Laufzeit einen Fehler bei der Auflösung von Abhängigkeiten aus. Dies gilt für alle von Aspire verwalteten Ressourcen, die mit Orleans.

Konfigurieren mit expliziter Verbindungszeichenfolge

Wenn Sie explizite Kontrolle über die Verbindungszeichenfolge benötigen, können Sie sie aus der Konfiguration lesen:

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

Konfigurieren des Clientprojekts Orleans

Konfigurieren Sie den Orleans Client für separate Clientprojekte ähnlich:

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

Referenz zu AppHost-Erweiterungsmethoden

Das Aspire.Hosting.Orleans Paket stellt die folgenden Erweiterungsmethoden bereit:

Kernmethoden

Methode	Description
builder.AddOrleans(name)	Fügt eine Ressource mit dem angegebenen Namen zur Orleans verteilten Anwendung hinzu.
.WithClusterId(id)	Legt die Orleans ClusterId fest. Akzeptiert eine Zeichenfolge oder ParameterResource. Wenn nicht angegeben, wird automatisch eine eindeutige ID generiert.
.WithServiceId(id)	Legt die Orleans ServiceId fest. Akzeptiert eine Zeichenfolge oder ParameterResource. Wenn nicht angegeben, wird automatisch eine eindeutige ID generiert.
.AsClient()	Gibt einen reinen Clientverweis auf die Orleans Ressource zurück (enthält keine Silofunktionen).
project.WithReference(orleans)	Fügt den Ressourcenverweis zu einem Projekt hinzu, wodurch die Orleans Konfigurationseinfügung aktiviert wird.

Hinweis

Wenn Sie eine Sicherungsressource mithilfe von .WithClustering(resource), .WithGrainStorage(name, resource) oder ähnlichen Methoden konfigurieren, enthält die Orleans-Ressource automatisch einen Verweis auf diese Sicherungsressource. Sie müssen .WithReference() nicht separat für jede Sicherungsressource aufrufen – nur .WithReference(orleans) ist erforderlich. Sie sollten jedoch .WaitFor() bei der Sicherungsressource verwenden, um sicherzustellen, dass sie bereit ist, bevor das Silo startet.

Clusterbildung

Methode	Description
.WithClustering(resource)	Orleans Konfiguriert das Clustering für die Verwendung der angegebenen Ressource (Redis, Azure Storage, Cosmos DB usw.).
.WithDevelopmentClustering()	Konfiguriert speicherinternes Clustering mit einem einzigen Host nur für die lokale Entwicklung. Nicht geeignet für die Produktion.

Getreidespeicherung

Methode	Description
.WithGrainStorage(name, resource)	Konfiguriert einen benannten Getreidespeicheranbieter mithilfe der angegebenen Ressource.
.WithMemoryGrainStorage(name)	Konfiguriert den Grain-Speicher im Arbeitsspeicher für den angegebenen Namen. Daten werden beim Siloneustart verloren.

Erinnerungen

Methode	Description
.WithReminders(resource)	Konfiguriert den Orleans Erinnerungsdienst mithilfe der angegebenen Ressource.
.WithMemoryReminders()	Konfiguriert Erinnerungen im Arbeitsspeicher für die Entwicklung. Erinnerungen gehen beim Siloneustart verloren.

Streamen

Methode	Description
.WithStreaming(name, resource)	Konfiguriert einen benannten Datenstromanbieter mithilfe der angegebenen Ressource (z. B. Azure Queue Storage).
.WithMemoryStreaming(name)	Konfiguriert das In-Memory-Streaming für die Entwicklung.
.WithBroadcastChannel(name)	Konfiguriert einen Übertragungskanalanbieter mit dem angegebenen Namen.

Grain-Verzeichnis

Methode	Description
.WithGrainDirectory(name, resource)	Konfiguriert ein benanntes Kornverzeichnis mithilfe der angegebenen Ressource.

Standard-Einstellungsmuster für Dienste

Aspire verwendet ein ServiceDefaults-Projektmuster, um gemeinsame Konfigurationen für alle Projekte gemeinsam zu nutzen. Für Orleansumfasst in der Regel Folgendes:

OpenTelemetry-Konfiguration

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

Azure Storage mit Aspire

Sie können Azure Storage-Ressourcen für Orleans Clustering und Persistenz verwenden:

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

Entwicklung im Vergleich zur Produktionskonfiguration

Aspire erleichtert den Wechsel zwischen Entwicklungs- und Produktionskonfigurationen:

Lokale Entwicklung (mit Emulatoren)

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

    // ...
}

Produktion (mit verwalteten Diensten)

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

    // ...
}

Gesundheitschecks

Aspire konfiguriert Integritätsprüfungsendpunkte automatisch. Sie können Orleans-spezifische Gesundheitsüberprüfungen hinzufügen:

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

Bewährte Methoden

1. Verwenden Sie ServiceDefaults: Gemeinsame Konfiguration (OpenTelemetry, Integritätsprüfungen) für alle Projekte mithilfe eines ServiceDefaults-Projekts freigeben.

2. Warten Sie auf Abhängigkeiten: Verwenden Sie immer .WaitFor(), um sicherzustellen, dass die Sicherungsressourcen (Redis, Datenbanken) bereit sind, bevor die Orleans Silos starten.

3. Konfigurieren von Replikaten: Verwenden Sie .WithReplicas(), um mehrere Siloinstanzen für Fehlertoleranz und Skalierbarkeit auszuführen.

4. Separate Clientprojekte: Für Web-Frontends verwenden Sie .AsClient(), um den Orleans Client-Only-Modus zu konfigurieren.

5. Verwenden Sie Emulatoren für die Entwicklung: Aspire kann Redis, Azure Storage (Azurite) und andere Abhängigkeiten lokal mit Containern ausführen.

6. Aktivieren Sie die verteilte Ablaufverfolgung: Konfigurieren Sie OpenTelemetry mit Orleans Quellnamen, um Grain-Calls im gesamten Cluster nachzuverfolgen.

Siehe auch

• Übersicht über .NET Aspire
• .NET Aspire-Einrichtung und -Tools
• Orleans Konfigurationshandbuch
• Orleans Redis-Anbieter
• Orleans Azure Storage-Anbieter

Die .NET Aspire-Integration wurde in Orleans 8.0 eingeführt. Für Orleans 7.0 können Sie weiterhin in Aspire-orchestrierten Umgebungen bereitstellen, aber das dedizierte Aspire.Hosting.Orleans Paket und seine Erweiterungsmethoden sind nicht verfügbar.

Erwägen Sie ein Upgrade auf Orleans 8.0 oder höher, um die Features der Aspire-Integration zu nutzen.

.NET Aspire Integration ist in Orleans 8.0 und höher verfügbar. Orleans 3.x unterstützt .NET Aspire nicht.