Intégration de .NET AspireOrleans

.NET Aspire offre une approche simplifiée de la création d’applications natives cloud avec prise en charge intégrée pour Orleans. Orleans À compter de la version 8.0, vous pouvez utiliser Aspire pour orchestrer votre Orleans cluster, gérer des ressources de stockage (telles que Redis ou Stockage Azure) et configurer automatiquement la découverte des services, l’observabilité et les vérifications d’intégrité.

Aperçu

Orleans l’intégration avec .NET Aspire utilise le Aspire.Hosting.Orleans paquet dans votre projet AppHost. Ce package fournit des méthodes d’extension pour :

Définir Orleans en tant que ressource distribuée
Configurer des fournisseurs de clustering (Redis, Stockage Azure, ADO.NET)
Configurer les fournisseurs de stockage des grains
Configurer des fournisseurs de rappels
Configurer des fournisseurs d’annuaires de grain
Modèle silo et relations client

Prerequisites

Avant d'utiliser Orleans avec Aspire, assurez-vous d'avoir :

Sdk .NET 8.0 ou version ultérieure
Charge de travail .NET Aspire
Un IDE avec prise en charge d’Aspire (Visual Studio 2022 17.9+, VS Code avec kit de développement C# ou JetBrains Rider)

Packages requis

Votre solution a besoin des références de package suivantes :

Projet AppHost

<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 Projet de silo

<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 projet client (s’il est séparé du 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>

Configurer l'AppHost

Le projet AppHost orchestre votre Orleans cluster et ses dépendances.

Cluster de base Orleans avec clustering Redis

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 avec stockage de grain et rappels

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

Séparer les projets de silo et de client

Lorsque votre Orleans client s’exécute dans un processus distinct (par exemple, un front-end web), utilisez la .AsClient() méthode :

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

Configurer le projet de silo Orleans

Dans votre Orleans projet de silo, configurez Orleans pour utiliser les ressources fournies par Aspire :

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

Conseil / Astuce

Lorsque vous utilisez .NET Aspire, le paramètre UseOrleans sans argument est généralement tout ce dont vous avez besoin. Aspire injecte la Orleans configuration (ID de cluster, ID de service, points de terminaison et paramètres du fournisseur) via des variables d’environnement qui Orleans lisent automatiquement. Vous n'avez besoin d'utiliser la surcharge de délégué UseOrleans(siloBuilder => {...}) que lorsque vous avez besoin d'une configuration manuelle supplémentaire au-delà de ce que fournit Aspire.

Important

Vous devez appeler la méthode appropriée AddKeyed* (par exemple AddKeyedRedisClient, AddKeyedAzureTableClient, ou AddKeyedAzureBlobClient) pour inscrire la ressource de support dans le conteneur d’injection de dépendances. Orleans les fournisseurs recherchent des ressources par leur nom de service clé : si vous ignorez cette étape, Orleans ne pourra pas résoudre cette ressource et générera une erreur de résolution de dépendance au moment de l’exécution. Cela s’applique à toutes les ressources gérées par Aspire utilisées avec Orleans.

Configurer avec une chaîne de connexion explicite

Si vous avez besoin d’un contrôle explicite sur la chaîne de connexion, vous pouvez le lire à partir de la configuration :

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

Configurer le Orleans projet client

Pour les projets clients distincts, configurez le Orleans client de la même façon :

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

Informations de référence sur les méthodes d’extension AppHost

Le Aspire.Hosting.Orleans package fournit ces méthodes d’extension :

Méthodes principales

Méthode	Descriptif
`builder.AddOrleans(name)`	Ajoute une Orleans ressource à l’application distribuée avec le nom spécifié.
`.WithClusterId(id)`	Définit le Orleans ClusterId. Accepte une chaîne ou `ParameterResource`. S’il n’est pas spécifié, un ID unique est généré automatiquement.
`.WithServiceId(id)`	Définit l’ID Orleans de service. Accepte une chaîne ou `ParameterResource`. S’il n’est pas spécifié, un ID unique est généré automatiquement.
`.AsClient()`	Retourne une référence client uniquement à la Orleans ressource (n’inclut pas les fonctionnalités de silo).
`project.WithReference(orleans)`	Ajoute la Orleans référence de ressource à un projet, ce qui active l’injection de configuration.

Note

Lorsque vous configurez une ressource de stockage à l'aide de .WithClustering(resource), .WithGrainStorage(name, resource), ou de méthodes similaires, la ressource Orleans inclut automatiquement une référence à cette ressource de stockage. Vous n'avez pas besoin d'appeler .WithReference() séparément pour chaque ressource d'assistance; seule l'appel à .WithReference(orleans) est nécessaire. Toutefois, vous devez utiliser .WaitFor() sur la ressource de support pour vous assurer qu’elle est prête avant le démarrage du silo.

Clustering

Méthode	Descriptif
`.WithClustering(resource)`	Configure le Orleans clustering pour utiliser la ressource spécifiée (Redis, Stockage Azure, Cosmos DB, etc.).
`.WithDevelopmentClustering()`	Configurer le clustering en mémoire sur un seul hôte pour le développement local seulement. Non adapté à la production.

Stockage des grains

Méthode	Descriptif
`.WithGrainStorage(name, resource)`	Configure un fournisseur de stockage de grain nommé à l’aide de la ressource spécifiée.
`.WithMemoryGrainStorage(name)`	Configure le stockage en mémoire du grain pour le nom spécifié. Les données sont perdues lors du redémarrage du silo.

Rappels

Méthode	Descriptif
`.WithReminders(resource)`	Configure le Orleans service de rappel à l’aide de la ressource spécifiée.
`.WithMemoryReminders()`	Configure les rappels en mémoire pour le développement. Les rappels sont perdus lors du redémarrage du silo.

Diffusion en continu

Méthode	Descriptif
`.WithStreaming(name, resource)`	Configurez un fournisseur de flux nommé à l’aide de la ressource spécifiée (par exemple, Azure Queue Storage).
`.WithMemoryStreaming(name)`	Configure le streaming en mémoire pour le développement.
`.WithBroadcastChannel(name)`	Configure un fournisseur de canal de diffusion avec le nom spécifié.

Répertoire de grain

Méthode	Descriptif
`.WithGrainDirectory(name, resource)`	Configure un répertoire de grain nommé en utilisant la ressource spécifiée.

Modèle par défaut de service

Aspire utilise un modèle de projet ServiceDefaults pour partager la configuration commune entre tous les projets. Cela inclut généralement pour Orleans :

Configuration d’OpenTelemetry

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

Stockage Azure avec Aspire

Vous pouvez utiliser des ressources stockage Azure pour Orleans le clustering et la persistance :

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

Configuration de développement et de production

Aspire facilite le basculement entre les configurations de développement et de production :

Développement local (à l’aide d’émulateurs)

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

    // ...
}

Production (à l’aide de services managés)

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

    // ...
}

Examens de santé

Aspire configure automatiquement les points de terminaison de contrôle d’intégrité. Vous pouvez ajouter des vérifications d’intégrité spécifiques à Orleans

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

Meilleures pratiques

Utilisez ServiceDefaults : partagez la configuration commune (OpenTelemetry, contrôles d’intégrité) dans tous les projets à l’aide d’un projet ServiceDefaults.
Attendez les dépendances : toujours utiliser .WaitFor() pour vous assurer que les ressources de stockage (Redis, bases de données) sont prêtes avant Orleans le démarrage des silos.
Configurer des réplicas : Utilisez .WithReplicas() pour exécuter plusieurs instances de silo, assurant ainsi la tolérance aux pannes et l'extensibilité.
Projets clients distincts : pour les serveurs frontaux web, utilisez .AsClient() pour configurer le Orleans mode client uniquement.
Utilisez des émulateurs pour le développement : Aspire peut exécuter Redis, Stockage Azure (Azurite) et d’autres dépendances localement à l’aide de conteneurs.
Activer le suivi distribué : configurez OpenTelemetry avec des noms de source pour tracer les appels de grains dans le cluster.

Voir aussi

L’intégration de .NET Aspire a été introduite dans Orleans la version 8.0. Pour Orleans la version 7.0, vous pouvez toujours déployer sur des environnements orchestrés par Aspire, mais le package dédié Aspire.Hosting.Orleans et ses méthodes d’extension ne sont pas disponibles.

Envisagez de mettre à niveau vers Orleans la version 8.0 ou ultérieure pour tirer parti des fonctionnalités d’intégration Aspire.

L'intégration de .NET Aspire est disponible dans Orleans 8.0 et ultérieures. Orleans 3.x ne prend pas en charge .NET Aspire.

Commentaires

Est-ce que cette page vous a été utile?

Last updated on 2026-01-23