intégration de .NET AspireOrleans
Orleans dispose d'un support intégré pour .NET.NET Aspire. .NET .NET Aspiremodèle d’application vous permet de décrire les services, les bases de données et d’autres ressources et l’infrastructure de votre application et leur relation entre eux. Orleans offre un moyen simple de créer des applications distribuées qui sont évolutives et tolérantes aux pannes de manière élastique. Vous pouvez utiliser .NET Aspire pour configurer et orchestrer Orleans et ses dépendances, par exemple en fournissant Orleans avec l’appartenance au cluster et le stockage.
Orleans est représenté en tant que ressource dans .NET Aspire. Contrairement à d’autres intégrations, l’intégration Orleans ne crée pas de conteneur et ne nécessite pas de package d’intégration client distinct. Au lieu de cela, vous terminez la configuration Orleans dans le projet hôte d’application .NET Aspire.
Remarque
Cette intégration nécessite Orleans version 8.1.0 ou ultérieure.
Intégration de l’hébergement
Le Orleans modélise un modèle d'intégration du service Orleans sous forme de type OrleansService. Pour accéder à ce type et à ces API, ajoutez le 📦Aspire.Hosting.Orleans package NuGet dans le projet hôte de l’application .
dotnet add package Aspire.Hosting.Orleans
Pour plus d’informations, consultez dotnet add package ou Gérer les dépendances des packages dans les applications .NET.
Ajouter une ressource Orleans
Dans votre projet hôte d’application, appelez AddOrleans pour ajouter et retourner un générateur de ressources de service Orleans. Le nom fourni à la ressource Orleans est à des fins de diagnostic. Pour la plupart des applications, une valeur de "default" suffit.
var orleans = builder.AddOrleans("default")
Utiliser Azure pour le stockage et le regroupement des tables et le stockage des grains
Dans une application Orleans, le bloc de construction fondamental est un grain. Les grains peuvent avoir des états durables. Vous devez stocker l’état durable d’un grain quelque part. Dans une application .NET.NET Aspire, Azure Blob Storage est un emplacement possible.
Orleans hôtes s’inscrivent dans une base de données et utilisent cette base de données pour se trouver et former un cluster. Ils stockent quels serveurs sont membres de quels silos dans une table de base de données. Vous pouvez utiliser des bases de données relationnelles ou NoSQL pour stocker ces informations. Dans une application .NET.NET Aspire, un choix populaire pour stocker cette table est Azure Table Storage.
Pour configurer Orleans avec le clustering et le stockage de grains dans Azure, installez le 📦Aspire.Hébergement.Azure.Stockage du package NuGet dans le projet hôte de l'application :
dotnet add package Aspire.Hosting.Azure.Storage
Dans votre projet hôte d’application, après avoir appelé AddOrleans, configurez la ressource Orleans avec le clustering et le stockage des grains à l’aide des méthodes WithClustering et WithGrainStorage respectivement :
// 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);
Le code précédent indique Orleans que tout service faisant référence à celui-ci doit également référencer la ressource clusteringTable.
Ajouter un projet de serveur Orleans dans l’hôte de l’application
Vous pouvez maintenant ajouter un nouveau projet, inscrit dans .NET Aspire orchestration, à votre solution en tant que serveur Orleans. Il prendra part au cluster Orleans en tant que silo avec des grains constituants. Référencez la ressource Orleans à partir de votre projet de serveur à l’aide de WithReference(orleans). Lorsque vous référencez la ressource Orleans à partir de votre service, ces ressources sont également référencées :
// 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);
Ajouter un projet client Orleans dans l’hôte d’application
Orleans clients communiquent avec les grains hébergés sur les serveurs Orleans. Dans une application .NET Aspire, par exemple, vous pouvez avoir un site Web en front-end qui appelle des grains dans un cluster Orleans. Référencez la ressource Orleans à partir de votre client Orleans à l’aide de WithReference(orleans.AsClient()).
// 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);
Créer le projet de serveur Orleans
Maintenant que le projet hôte d’application est terminé, vous pouvez implémenter le projet de serveur Orleans. Commençons par ajouter les packages NuGet nécessaires :
Dans le dossier du projet de serveur Orleans, exécutez les commandes suivantes :
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
Ensuite, dans le fichier Program.cs de votre projet de serveur Orleans, ajoutez les clients Azure Stockage Blob et tables, puis appelez UseOrleans.
var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults();
builder.AddKeyedAzureTableClient("clustering");
builder.AddKeyedAzureBlobClient("grain-state");
builder.UseOrleans();
Le code suivant est un exemple complet d’un projet de serveur Orleans, y compris un grain nommé 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;
}
}
Créer un projet client Orleans
Dans le projet client Orleans, ajoutez les mêmes packages 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
Ensuite, dans le fichier Program.cs de votre projet client Orleans, ajoutez le client de stockage de table Azure, puis appelez UseOrleansClient.
builder.AddKeyedAzureTableClient("clustering");
builder.UseOrleansClient();
Le code suivant est un exemple complet d’un projet client Orleans. Il appelle le grain CounterGrain défini dans l’exemple de serveur Orleans ci-dessus :
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();
Activation de OpenTelemetry
Par convention, .NET.NET Aspire solutions incluent un projet pour définir la configuration et le comportement par défaut de votre service. Le projet est appelé projet de défauts de service , et les modèles le créent avec un nom se terminant par ServiceDefaults. Pour configurer Orleans pour OpenTelemetry dans .NET Aspire, appliquez la configuration à votre projet de service par défaut en suivant le guide d’observabilité Orleans.
Modifiez la méthode ConfigureOpenTelemetry pour ajouter les mètres Orleans et les instruments de traçage . L’extrait de code suivant montre le fichier de Extensions.cs modifié à partir d’un projet de service par défaut qui inclut des métriques et des traces de 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;
}
Fournisseurs pris en charge
L’intégration OrleansAspire prend en charge un sous-ensemble limité de fournisseurs Orleans aujourd’hui :
- Clustering:
- Redis
- tables de stockage Azure
- Persistance:
- Redis
- tables de stockage Azure
- Blobs de stockage Azure
- Rappels:
- Redis
- tables de stockage Azure
- Répertoire des grains
- Redis
- tables de stockage Azure
Les fournisseurs de streaming ne sont pas pris en charge à partir de Orleans version 8.1.0.
