Skip to content
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

.NET Aspire 9.0 - GA Release content #1867

Merged
merged 127 commits into from
Nov 12, 2024
Merged
Changes from 1 commit
Commits
Show all changes
127 commits
Select commit Hold shift + click to select a range
fa00483
Initial bits...WIP, early draft
IEvangelist Oct 17, 2024
a0b3560
Add draft SDK content
IEvangelist Oct 17, 2024
5b5bc86
A few more bits
IEvangelist Oct 17, 2024
4e52074
SDK
IEvangelist Oct 17, 2024
0bcaa9c
Tons of updates, additions, removals, and whatnot.
IEvangelist Oct 17, 2024
143f6d1
Sweeping updates
IEvangelist Oct 17, 2024
9b707d5
Fix links
IEvangelist Oct 21, 2024
77490b1
Initial parts of eventing
IEvangelist Oct 23, 2024
4b9c5da
Fix a few build issues
IEvangelist Oct 23, 2024
9894b7f
More issues
IEvangelist Oct 23, 2024
064a1e3
Add eventing to TOC
IEvangelist Oct 23, 2024
063223f
Added txt for console output
IEvangelist Oct 24, 2024
4a64b24
Eventing API content, getting closer
IEvangelist Oct 24, 2024
391c20b
A bit more clean up
IEvangelist Oct 24, 2024
532701a
Fix hosting meilisearch
IEvangelist Oct 24, 2024
731bbc7
More SDK updates
IEvangelist Oct 24, 2024
f9dd2d6
More SDK clarification
IEvangelist Oct 24, 2024
b214084
index tweaks
IEvangelist Oct 24, 2024
771d769
Try using uppercase slug
IEvangelist Oct 24, 2024
c00cfa1
Fix publish API
IEvangelist Oct 24, 2024
f36d9bd
Add zones to upgrade
IEvangelist Oct 24, 2024
98912c3
Some breaking changes
IEvangelist Oct 24, 2024
eecaf72
More links to API change
IEvangelist Oct 24, 2024
228976f
Add API removal text
IEvangelist Oct 24, 2024
fe16ee7
TOC updates
IEvangelist Oct 24, 2024
ed6f256
More breaking changes and fix podman
IEvangelist Oct 25, 2024
0b74e12
Trying a few things with the TOC
IEvangelist Oct 25, 2024
59d1080
Generate the breaking-changes
IEvangelist Oct 28, 2024
5739670
Clean up
IEvangelist Oct 28, 2024
8e8bdb4
Add AI metadata
IEvangelist Oct 28, 2024
d73e874
Fix TOC
IEvangelist Oct 28, 2024
40f95ec
Add a few more bits for the upgrade content
IEvangelist Oct 28, 2024
301084c
Fix lightbox attribute
IEvangelist Oct 28, 2024
e3a22e3
Missing attribute
IEvangelist Oct 28, 2024
8e25e09
New line
IEvangelist Oct 28, 2024
09928e7
Edit pass
IEvangelist Oct 29, 2024
7b57ad5
Upgrade quickstart to .NET Aspire 9.0, and update some dashboard images
IEvangelist Oct 29, 2024
5dfd2fd
Update dashboard bits, images, and add actions section
IEvangelist Oct 29, 2024
4e3bb29
Fix link, no troubleshooting
IEvangelist Oct 29, 2024
09274a4
More resource action updates
IEvangelist Oct 29, 2024
bbc08b7
Remove edges
IEvangelist Oct 29, 2024
deca6eb
Fixes #1823
IEvangelist Oct 29, 2024
db325da
Add details for app host lifecylce
IEvangelist Oct 29, 2024
ce5c3a3
Demote alert
IEvangelist Oct 29, 2024
dd2448e
Edit pass
IEvangelist Oct 29, 2024
769cb8d
Edit pass and additions.
IEvangelist Oct 30, 2024
f462e04
Edit pass and highlighting
IEvangelist Oct 30, 2024
a891785
Let's see how far we've come
IEvangelist Oct 30, 2024
f57e379
Lots of updates
IEvangelist Oct 30, 2024
b44c2f8
Move a few things
IEvangelist Oct 30, 2024
03a7e90
Added error
IEvangelist Oct 30, 2024
cab8129
Remove discards.
IEvangelist Oct 30, 2024
bb078f1
Apply suggestions from code review
IEvangelist Oct 31, 2024
588c6b2
Additional feedback
IEvangelist Oct 31, 2024
8afb854
Fix learn site issue reporting.
IEvangelist Oct 31, 2024
5fa5c54
Fix link...
IEvangelist Oct 31, 2024
393acf1
Fixes #2003
IEvangelist Oct 31, 2024
804ff3b
Edit pass on explore dashboard
IEvangelist Oct 31, 2024
d2e976c
More clean up
IEvangelist Oct 31, 2024
1f1e04e
Add details for WaitFor/Completion APIs.
IEvangelist Oct 31, 2024
1bdf2e2
Fixes from build report.
IEvangelist Oct 31, 2024
1073ca3
Remove snippets for Functions
IEvangelist Oct 31, 2024
c4f6a0a
Update overview.md
mitchdenny Nov 1, 2024
8fe602f
Update dotnet-aspire-sdk.md
mitchdenny Nov 1, 2024
6d40011
Update eventing.md
mitchdenny Nov 1, 2024
8d4796a
Update eventing.md
mitchdenny Nov 1, 2024
0fbd03a
Update docs/app-host/eventing.md
IEvangelist Nov 1, 2024
5088eae
Add Ollama integration updates.
IEvangelist Nov 4, 2024
a77a788
Fix headings and sections
IEvangelist Nov 4, 2024
ce1e4d2
Lots of updates and fixes
IEvangelist Nov 4, 2024
a9acaca
Upgrade a few more bits, quickstart and setup/tooling
IEvangelist Nov 4, 2024
5e33099
Fix build
IEvangelist Nov 4, 2024
ce77e3a
Additions, version fixes, etc.
IEvangelist Nov 4, 2024
a4adf43
Clean up some of the image/diagrams
IEvangelist Nov 4, 2024
bdbe40b
Fixing updated APIs
IEvangelist Nov 4, 2024
68a8d22
Added a few bits to address #1704
IEvangelist Nov 4, 2024
3c81ef3
Addresses #2004
IEvangelist Nov 4, 2024
7924855
Apply suggestions from code review
IEvangelist Nov 5, 2024
b6fb7bf
Fix broken link
IEvangelist Nov 5, 2024
0538a06
Rewrite the toolkit overview. Update some images
IEvangelist Nov 5, 2024
37bf565
Remove images
IEvangelist Nov 5, 2024
533d3c7
Fix link and minor edits
IEvangelist Nov 5, 2024
5092c0f
Move Azure Cache for Redis to the bottom
IEvangelist Nov 5, 2024
c44219b
Fix MD lint
IEvangelist Nov 5, 2024
e0c0651
Edit pass on the Orleans content. Also, fixes #1818
IEvangelist Nov 5, 2024
19fefa5
Move Azure PostgreSQL bits to the bottom of the page
IEvangelist Nov 5, 2024
839f40e
Try fixing the zones
IEvangelist Nov 5, 2024
71523f8
Fix MD lint error
IEvangelist Nov 5, 2024
d88ee90
Fix more broken zones
IEvangelist Nov 5, 2024
d8596cf
Add see also section
IEvangelist Nov 5, 2024
720d8fb
Setup and tooling TOC updates
IEvangelist Nov 5, 2024
143ba50
Re-order TOC
IEvangelist Nov 5, 2024
fc4409a
Update docs/app-host/eventing.md
IEvangelist Nov 6, 2024
dd19223
Updates for the tutorial on adding Aspire to existing app
IEvangelist Nov 6, 2024
f3c6697
Repurpose RC1, redirects, edit pass, links, etc.
IEvangelist Nov 6, 2024
0663562
Fix the TOC
IEvangelist Nov 6, 2024
9fd867d
Edit pass and cleanup of explore and what's new in .NET Aspire 9
IEvangelist Nov 6, 2024
e11660d
Added custom command article
IEvangelist Nov 7, 2024
e81ac0c
Add to TOC
IEvangelist Nov 7, 2024
c134772
Fix #2016, update to latest templates
IEvangelist Nov 7, 2024
48610f8
Fix #2022
IEvangelist Nov 7, 2024
323c215
A bit of container love
IEvangelist Nov 8, 2024
fb8b2e6
A bit more clean up
IEvangelist Nov 8, 2024
202203b
Be more consistent with references to NuGet packages
IEvangelist Nov 8, 2024
4840b7d
Fix #2027
IEvangelist Nov 8, 2024
d5c9704
Fix regex replace. :|
IEvangelist Nov 8, 2024
81027b4
Fix #2026
IEvangelist Nov 8, 2024
0a2510b
Apply suggestions from code review
IEvangelist Nov 8, 2024
0542c51
A few bits of peer feedback
IEvangelist Nov 8, 2024
38b7424
Some fixes related to #2024
IEvangelist Nov 8, 2024
2f6cdf4
Fix #2017
IEvangelist Nov 8, 2024
13bae6d
Apply suggestions from code review
IEvangelist Nov 9, 2024
20e1f57
Fix suggestion
IEvangelist Nov 9, 2024
5c24630
Update docs/fundamentals/aspire-sdk-templates.md
IEvangelist Nov 9, 2024
a728261
A few peer bits of feedback
IEvangelist Nov 9, 2024
396c1a9
Fix (update) create new project images
IEvangelist Nov 11, 2024
4622d3f
Fix include and delete legacy media
IEvangelist Nov 11, 2024
a4a4e20
Isolate to selection, readd media
IEvangelist Nov 11, 2024
34a0709
Fix #1993
IEvangelist Nov 11, 2024
a7f45a0
A few more bits of cleanup
IEvangelist Nov 11, 2024
eea1284
Remove .NET Aspire SDK as a prereq
IEvangelist Nov 11, 2024
aaf77e5
A few bits of additional context.
IEvangelist Nov 12, 2024
f4dec25
More links
IEvangelist Nov 12, 2024
b6c0c50
Tidy
IEvangelist Nov 12, 2024
d462fa0
Consistent sentence
IEvangelist Nov 12, 2024
de6effb
Bump DOTNET_VERSION
IEvangelist Nov 12, 2024
4a137b8
Remove install of workload
IEvangelist Nov 12, 2024
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Initial parts of eventing
  • Loading branch information
IEvangelist committed Nov 11, 2024
commit 77490b139d59e3893edeea1b5d9d5c135b24d03b
69 changes: 69 additions & 0 deletions docs/app-host/eventing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
---
title: Eventing in .NET Aspire
description: Learn how to use the .NET eventing features with .NET Aspire.
ms.date: 10/23/2024
---

# Eventing in .NET Aspire

In .NET Aspire, you use eventing to enable scenarios where you need to publish and subscribe to events during various [app host](xref:dotnet/aspire/app-host#app-host-life-cycles) life cycles. Generally speaking, eventing is more flexible than life cycle events, as you can run arbitrary code and you have more finite control. The eventing mechanisms in .NET Aspire are core to the [📦 Aspire.Hosting](https://www.nuget.org/packages/Aspire.Hosting) NuGet package. This package provides a set of interfaces and classes in the <xref:Aspire.Hosting.Eventing> namespace that you use to publish and subscribe to events in your .NET Aspire app host project. Eventing is scoped to the app host itself and the resources within.

In this article, you learn how to use the eventing features in .NET Aspire.

## App host eventing

The following events are available in the app host and are raised in the following order:

1. <xref:Aspire.Hosting.ApplicationModel.BeforeStartEvent>: This event is raised before the app host starts.
1. <xref:Aspire.Hosting.ApplicationModel.AfterEndpointsAllocatedEvent>: This event is raised after the app host has allocated endpoints.
1. <xref:Aspire.Hosting.ApplicationModel.AfterResourcesCreatedEvent>: This event is raised after the app host has created resources.

All of the preceding events are analogous to the [app host life cycles](xref:dotnet/aspire/app-host#app-host-life-cycles). That is, they could also be handled by an implementation of the <xref:Aspire.Hosting.Lifecycle.IDistributedApplicationLifecycleHook>. With the eventing API, however, you can run arbitrary code when these events are raised and event define custom events—any event that implements the <xref:Aspire.Hosting.Eventing.IDistributedApplicationEvent> interface.

### Subscribe to app host events

To subscribe to the built-in app host events, use the eventing API. After you have a distributed application builder instance, walk up to the <xref:Aspire.Hosting.IDistributedApplicationBuilder.Eventing?displayProperty=nameWithType> property and call the <xref:Aspire.Hosting.Eventing.IDistributedApplicationEventing.Subscribe*?displayProperty=nameWithType> API. Consider the following sample app host _Program.cs_ file:

:::code source="snippets/AspireApp/AspireApp.AppHost/Program.cs":::

The preceding code is based on the starter template with the addition of the subscribe calls. The `Subscribe<T>` API returns a <xref:Aspire.Hosting.Eventing.DistributedApplicationEventSubscription> instance that you can use to unsubscribe from the event. It's common to discard these, as you don't usually need to unsubscribe from events as the entire app is torn down when the app host is shut down.

When the app host is run, by the time the .NET Aspire dashboard is displayed, you should see the following log output in the console:

```Output
info: Program[0]
1. BeforeStartEvent
info: Aspire.Hosting.DistributedApplication[0]
Aspire version: 9.0.0
info: Aspire.Hosting.DistributedApplication[0]
Distributed application starting.
info: Aspire.Hosting.DistributedApplication[0]
Application host directory is: ..\AspireApp\AspireApp.AppHost
info: Program[0]
2. AfterEndpointsAllocatedEvent
info: Aspire.Hosting.DistributedApplication[0]
Now listening on: https://localhost:17178
info: Aspire.Hosting.DistributedApplication[0]
Login to the dashboard at https://localhost:17178/login?t=<YOUR_TOKEN>
info: Program[0]
3. AfterResourcesCreatedEvent
info: Aspire.Hosting.DistributedApplication[0]
Distributed application started. Press Ctrl+C to shut down.
```

## Resource eventing

In addition to the app host events, you can also subscribe to resource events. Resource events are raised when a resource is created, updated, or deleted. The following events are available:

<xref:Aspire.Hosting.Eventing.IDistributedApplicationResourceEvent>

## Event dispatch behavior

When events are dispatched, you can control how the events are dispatched to subscribers. The event dispatch behavior is controlled by the <xref:Aspire.Hosting.Eventing.EventDispatchBehavior> enumeration. The following behaviors are available:

- <xref:Aspire.Hosting.Eventing.EventDispatchBehavior.BlockingSequential>: Fires events sequentially and blocks until they're all processed.
- <xref:Aspire.Hosting.Eventing.EventDispatchBehavior.BlockingConcurrent>: Fires events concurrently and blocks until they are all processed.
- <xref:Aspire.Hosting.Eventing.EventDispatchBehavior.NonBlockingSequential>: Fires events sequentially but doesn't block.
- <xref:Aspire.Hosting.Eventing.EventDispatchBehavior.NonBlockingConcurrent>: Fires events concurrently but doesn't block.

The default behavior is <xref:Aspire.Hosting.Eventing.EventDispatchBehavior.BlockingSequential>. To override this behavior, when calling a publishing API such as <xref:Aspire.Hosting.Eventing.IDistributedApplicationEventing.PublishAsync*>, provide the desired behavior as an argument.
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<Project Sdk="Microsoft.NET.Sdk.Web">

<PropertyGroup>
<TargetFramework>net9.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>

<ItemGroup>
<ProjectReference Include="..\AspireApp.ServiceDefaults\AspireApp.ServiceDefaults.csproj" />
</ItemGroup>

</Project>
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
var builder = WebApplication.CreateBuilder(args);

// Add service defaults & Aspire client integrations.
builder.AddServiceDefaults();

// Add services to the container.
builder.Services.AddProblemDetails();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.UseExceptionHandler();

var summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
var forecast = Enumerable.Range(1, 5).Select(index =>
new WeatherForecast
(
DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
Random.Shared.Next(-20, 55),
summaries[Random.Shared.Next(summaries.Length)]
))
.ToArray();
return forecast;
});

app.MapDefaultEndpoints();

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
{
"$schema": "https://json.schemastore.org/launchsettings.json",
"profiles": {
"http": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"launchUrl": "weatherforecast",
"applicationUrl": "http://localhost:5562",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
},
"https": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"launchUrl": "weatherforecast",
"applicationUrl": "https://localhost:7482;http://localhost:5562",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
},
"AllowedHosts": "*"
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<Project Sdk="Microsoft.NET.Sdk">

<Sdk Name="Aspire.AppHost.Sdk" Version="9.0.0-rc.1.24511.1" />

<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net9.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<IsAspireHost>true</IsAspireHost>
<UserSecretsId>7b352f08-305b-4032-9a21-90deb02efc04</UserSecretsId>
</PropertyGroup>

<ItemGroup>
<ProjectReference Include="..\AspireApp.ApiService\AspireApp.ApiService.csproj" />
<ProjectReference Include="..\AspireApp.Web\AspireApp.Web.csproj" />
</ItemGroup>

<ItemGroup>
<PackageReference Include="Aspire.Hosting.AppHost" Version="9.0.0-rc.1.24511.1" />
<PackageReference Include="Aspire.Hosting.Redis" Version="9.0.0-rc.1.24511.1" />
</ItemGroup>

</Project>
47 changes: 47 additions & 0 deletions docs/app-host/snippets/AspireApp/AspireApp.AppHost/Program.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

var apiService = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
.WithExternalHttpEndpoints()
.WithReference(cache)
.WaitFor(cache)
.WithReference(apiService)
.WaitFor(apiService);

_ = builder.Eventing.Subscribe<BeforeStartEvent>(
static (@event, cancellationToken) =>
{
var logger = @event.Services.GetRequiredService<ILogger<Program>>();

logger.LogInformation("1. BeforeStartEvent");

return Task.CompletedTask;
});

_ = builder.Eventing.Subscribe<AfterEndpointsAllocatedEvent>(
static (@event, cancellationToken) =>
{
var logger = @event.Services.GetRequiredService<ILogger<Program>>();

logger.LogInformation("2. AfterEndpointsAllocatedEvent");

return Task.CompletedTask;
});

_ = builder.Eventing.Subscribe<AfterResourcesCreatedEvent>(
static (@event, cancellationToken) =>
{
var logger = @event.Services.GetRequiredService<ILogger<Program>>();

logger.LogInformation("3. AfterResourcesCreatedEvent");

return Task.CompletedTask;
});

builder.Build().Run();
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
{
"$schema": "https://json.schemastore.org/launchsettings.json",
"profiles": {
"https": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"applicationUrl": "https://localhost:17178;http://localhost:15142",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development",
"DOTNET_ENVIRONMENT": "Development",
"DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21137",
"DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22259"
}
},
"http": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"applicationUrl": "http://localhost:15142",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development",
"DOTNET_ENVIRONMENT": "Development",
"DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19091",
"DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20229"
}
}
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning",
"Aspire.Hosting.Dcp": "Warning"
}
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
<Project Sdk="Microsoft.NET.Sdk">

<PropertyGroup>
<TargetFramework>net9.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<IsAspireSharedProject>true</IsAspireSharedProject>
</PropertyGroup>

<ItemGroup>
<FrameworkReference Include="Microsoft.AspNetCore.App" />

<PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="8.10.0" />
<PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="9.0.0-rc.1.24511.1" />
<PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.9.0" />
<PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.9.0" />
<PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.9.0" />
<PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.9.0" />
<PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.9.0" />
</ItemGroup>

</Project>
Loading