-
Notifications
You must be signed in to change notification settings - Fork 6.1k
Update Orleans and Aspire integration documentation #54201
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from 1 commit
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,20 +1,20 @@ | ||
| --- | ||
| title: Orleans and .NET Aspire integration | ||
| description: Learn how to integrate Orleans with .NET Aspire for cloud-native development. | ||
| title: Orleans and Aspire integration | ||
| description: Learn how to integrate Orleans with Aspire for cloud-native development. | ||
| ms.date: 01/21/2026 | ||
| ms.topic: concept-article | ||
| zone_pivot_groups: orleans-version | ||
| --- | ||
|
|
||
| # Orleans and .NET Aspire integration | ||
| # Orleans and Aspire integration | ||
|
gewarren marked this conversation as resolved.
|
||
|
|
||
| :::zone target="docs" pivot="orleans-8-0,orleans-9-0,orleans-10-0" | ||
|
|
||
| [.NET Aspire](/dotnet/aspire/get-started/aspire-overview) provides a streamlined approach to building cloud-native applications with built-in support for Orleans. Starting with Orleans 8.0, you can use Aspire to orchestrate your Orleans cluster, manage backing resources (like Redis or Azure Storage), and automatically configure service discovery, observability, and health checks. | ||
| [Aspire](https://aspire.dev/integrations/frameworks/orleans) provides a streamlined approach to building cloud-native applications with built-in support for Orleans. Starting with Orleans 8.0, you can use Aspire to orchestrate your Orleans cluster, manage backing resources (like Redis or Azure Storage), and automatically configure service discovery, observability, and health checks. | ||
|
gewarren marked this conversation as resolved.
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The original link makes more sense to me here.
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I thought about that too. To me, someone is here because they probably know what aspire is and are more interested in integrating the two techs. So a link to the integration would make sense over a "what is aspire" But I can go either way. |
||
|
|
||
| ## Overview | ||
|
|
||
| Orleans integration with .NET Aspire uses the `Aspire.Hosting.Orleans` package in your AppHost project. This package provides extension methods to: | ||
| Orleans integration with Aspire uses the `Aspire.Hosting.Orleans` package in your AppHost project. This package provides extension methods to: | ||
|
gewarren marked this conversation as resolved.
Outdated
|
||
|
|
||
| - Define Orleans as a distributed resource | ||
| - Configure clustering providers (Redis, Azure Storage, ADO.NET) | ||
|
|
@@ -28,8 +28,8 @@ Orleans integration with .NET Aspire uses the `Aspire.Hosting.Orleans` package i | |
| Before using Orleans with Aspire, ensure you have: | ||
|
|
||
| - [.NET 8.0 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) or later | ||
| - [.NET Aspire workload](/dotnet/aspire/fundamentals/setup-tooling) | ||
| - An IDE with Aspire support (Visual Studio 2022 17.9+, VS Code with C# Dev Kit, or JetBrains Rider) | ||
| - [Aspire cli](https://aspire.dev/get-started/install-cli/) | ||
|
gewarren marked this conversation as resolved.
Outdated
|
||
| - An IDE with Aspire support (Visual Studio 2022 17.9+, VS Code with [`microsoft-aspire.aspire-vscode`](https://marketplace.visualstudio.com/items?itemName=microsoft-aspire.aspire-vscode), or JetBrains Rider) | ||
|
|
||
| ## Required packages | ||
|
|
||
|
|
@@ -72,7 +72,7 @@ In your Orleans silo project, configure Orleans to use the Aspire-provided resou | |
| :::code language="csharp" source="snippets/aspire/Silo/SiloProgram.cs" id="silo_basic_config"::: | ||
|
|
||
| > [!TIP] | ||
| > When using .NET Aspire, the parameterless <xref:Microsoft.Extensions.Hosting.GenericHostExtensions.UseOrleans*> is typically all you need. Aspire injects Orleans configuration (cluster ID, service ID, endpoints, and provider settings) via environment variables that Orleans reads automatically. You only need the delegate overload `UseOrleans(siloBuilder => {...})` when you require additional manual configuration beyond what Aspire provides. | ||
| > When using Aspire, the parameterless <xref:Microsoft.Extensions.Hosting.GenericHostExtensions.UseOrleans*> is typically all you need. Aspire injects Orleans configuration (cluster ID, service ID, endpoints, and provider settings) via environment variables that Orleans reads automatically. You only need the delegate overload `UseOrleans(siloBuilder => {...})` when you require additional manual configuration beyond what Aspire provides. | ||
|
|
||
| > [!IMPORTANT] | ||
| > You must call the appropriate `AddKeyed*` method (such as `AddKeyedRedisClient`, `AddKeyedAzureTableClient`, or `AddKeyedAzureBlobClient`) to register the backing resource in the dependency injection container. Orleans providers look up resources by their keyed service name—if you skip this step, Orleans won't be able to resolve the resource and will throw a dependency resolution error at runtime. This applies to all Aspire-managed resources used with Orleans. | ||
|
|
@@ -189,8 +189,7 @@ Aspire automatically configures health check endpoints. You can add Orleans-spec | |
|
|
||
| ## See also | ||
|
|
||
| - [.NET Aspire overview](/dotnet/aspire/get-started/aspire-overview) | ||
| - [.NET Aspire setup and tooling](/dotnet/aspire/fundamentals/setup-tooling) | ||
| - [Aspire overview](https://aspire.dev/get-started/prerequisites/) | ||
|
gewarren marked this conversation as resolved.
Outdated
|
||
| - [Orleans configuration guide](configuration-guide/index.md) | ||
| - [Orleans Redis providers](../grains/grain-persistence/index.md#redis-grain-persistence) | ||
| - [Orleans Azure Storage providers](../grains/grain-persistence/azure-storage.md) | ||
|
|
@@ -199,14 +198,14 @@ Aspire automatically configures health check endpoints. You can add Orleans-spec | |
|
|
||
| :::zone target="docs" pivot="orleans-7-0" | ||
|
|
||
| .NET Aspire integration was introduced in Orleans 8.0. For Orleans 7.0, you can still deploy to Aspire-orchestrated environments, but the dedicated `Aspire.Hosting.Orleans` package and its extension methods are not available. | ||
| Aspire integration was introduced in Orleans 8.0. For Orleans 7.0, you can still deploy to Aspire-orchestrated environments, but the dedicated `Aspire.Hosting.Orleans` package and its extension methods are not available. | ||
|
|
||
| Consider upgrading to Orleans 8.0 or later to take advantage of the Aspire integration features. | ||
|
|
||
| :::zone-end | ||
|
|
||
| :::zone target="docs" pivot="orleans-3-x" | ||
|
|
||
| .NET Aspire integration is available in Orleans 8.0 and later. Orleans 3.x does not support .NET Aspire. | ||
| Aspire integration is available in Orleans 8.0 and later. Orleans 3.x does not support .NET Aspire. | ||
|
gewarren marked this conversation as resolved.
Outdated
|
||
|
|
||
| :::zone-end | ||
Uh oh!
There was an error while loading. Please reload this page.