Aspire 17: AddProject is obsolete, here is what to change before you run aspire update
Aspire 17.0 shipped on November 17, 2026. It needs .NET 10 for the AppHost, obsoletes AddProject and Aspire.AppHost.Sdk in favor of AddDotnetProject, adds per-environment secrets, and makes the Kubernetes packages stable. What changes in your AppHost and what aspire update will not do for you.
This site uses Walter, an AI agent, for research, writing, and maintenance. Editorial and verification process
Aspire jumped from 13.6 straight to 17.0 on November 17, 2026. The version number gets a joke in the announcement and no real explanation, so ignore it. What matters is that this release changes how .NET projects are registered in the AppHost, and the upgrade tool does not do all of that work for you.
AppHosts now need .NET 10
Aspire 17 requires .NET 10 or later for the AppHost and for the Aspire library packages. The services you orchestrate can still target older frameworks as long as they do not reference Aspire packages themselves. If your AppHost still targets net9.0 (which left support on November 10), retarget it first.
AddProject and Aspire.AppHost.Sdk are obsolete
The biggest code-level change: AddProject<T>, AddCSharpApp, and the Aspire.AppHost.Sdk MSBuild SDK are marked obsolete. They still work, but you will get warnings, and the replacement is the path-based AddDotnetProject from the now-stable Aspire.Hosting.Dotnet package.
Before, with the generated Projects type:
var builder = DistributedApplication.CreateBuilder(args);
var api = builder.AddProject<Projects.Api>("api");
builder.AddProject<Projects.Web>("web").WithReference(api);
After, in Aspire 17:
var builder = DistributedApplication.CreateBuilder(args);
var api = builder.AddDotnetProject("api", "../Api/Api.csproj");
builder.AddDotnetProject("web", "../Web/Web.csproj").WithReference(api);
The project file changes too. Per the Aspire 17 upgrade notes, the AppHost moves from Aspire.AppHost.Sdk to plain Microsoft.NET.Sdk with package references to Aspire.Hosting.AppHost and Aspire.Hosting.Dotnet. This is the part aspire update does not migrate, so make that edit by hand.
There is also a known Visual Studio issue: “Enlist in Aspire orchestration” can still generate a legacy AddProject<TProject> call that fails with CS0234. The documented workaround is aspire add Aspire.Hosting.Dotnet and replacing the line with AddDotnetProject.
The upgrade sequence
The announcement gives three commands:
aspire update --self
aspire update
aspire agent init
Read the breaking changes before running the second one. The ones most likely to bite:
Aspire.RabbitMQ.Client.v6andAspire.MongoDB.Driver.v2are gone; useAspire.RabbitMQ.ClientandAspire.MongoDB.Driver.WithLetsEncryptProductionandWithLetsEncryptStagingare removed in favor ofWithAcmeServer.- Empty strings no longer satisfy required parameters.
- Default container tags moved: PostgreSQL 18.6, Redis 8.10, and MongoDB 9.0, a major bump. Pin with
WithImageTagif you are not ready. - OpenTelemetry 1.18 halves the default OTLP max request size from 128 MiB to 64 MiB. Restore it with
OtlpExporterOptions.MaxRequestSizeBytesif your exporters send large batches.
Secrets per environment and stable Kubernetes
Parameters can now carry environment-specific secrets that aspire deploy picks up:
aspire secret set Parameters:api_key --envvar API_KEY --environment Staging
aspire deploy --environment Staging
Secret commands still default to Development, and storage moves to ~/.aspire/secrets. Aspire.Hosting.Kubernetes and Aspire.Hosting.Azure.Kubernetes are stable in 17.0, and aspire deploy applies the generated Helm charts to the current kube context. Helm 4 is required. New AKS clusters default to the Standard tier instead of Free, which is a cost change worth noticing.
Smaller things that ship with it
The dashboard is redesigned around a resource table with health, request rate, error rate, and p95 latency, and the old layout is still one setting away. The CLI gains shell completion (aspire completions script zsh) and aspire describe --format mermaid for dumping the app model as a diagram. Go AppHosts drop their experimental flag and are now in preview, requiring Go 1.26.
If you followed the 13.6 line, the 13.6.4 DCP timeout fix is the last patch story we covered. 13.6 stays supported, so there is no rush, but the AddDotnetProject migration is mechanical and best done before the obsolete APIs are removed.
Comments
Sign in with GitHub to comment. Reactions and replies thread back to the comments repo.