search

dotnet / docs-aspire

This repository contains .NET Aspire documentation.
https://learn.microsoft.com/dotnet/aspire
MIT License
81 stars 108 forks source link

[Breaking Change] Update docs to Aspire.Hosting breaking changes in preview5 #535

Closed eerhardt closed 7 months ago

eerhardt commented 8 months ago

Describe the issue or suggestion

We are making 2 breaking changes in AppHost projects in Aspire preview5.

  1. All AppHost projects need to change which PackageReference they have.
-<PackageReference Include="Aspire.Hosting" Version="..." />
+<PackageReference Include="Aspire.Hosting.AppHost" Version="..." />
  1. The resources that are used in the AppHost are now split into separate, dedicated nuget packages. For example, if your app needs a PostgreSQL database, you need a new reference:
+<PackageReference Include="Aspire.Hosting.PostgreSQL" Version="..." />

All packages that were split out of Aspire.Hosting:

cc @IEvangelist

Associated WorkItem - 238736

mitchdenny commented 8 months ago

@IEvangelist further to this we have an incoming PR (going to land in the next 24 hours) which gives the Aspire.Hosting.Azure package the same treatment:

https://github.com/dotnet/aspire/pull/3062

New packages are:

IEvangelist commented 7 months ago

Hey @eerhardt - would Aspire.Hosting.Orleans be included in this too? /cc @ReubenBond

Also, what about Aspire.Hosting.Dapr and Aspire.Hosting.PostgreSQL?

And @mitchdenny, what about Aspire.Hosting.Azure.EventHubs and Aspire.Hosting.Azure.KeyVault?

Finally, I thought that Cognitive Services was a legacy name, and that it was officially rebranded as "Azure AI" now. If that's the case, then I'd argue we should change the name of the new hosting package:

- Aspire.Hosting.Azure.CognitiveServices
+ Aspire.Hosting.Azure.AI

Update I just got confirmation from the Azure AI docs PM, who said it's now called "Azure AI Services".

eerhardt commented 7 months ago

would Aspire.Hosting.Orleans be included in this too? /cc @ReubenBond Also, what about Aspire.Hosting.Dapr

Orleans and Dapr were already split out. There is no change there as they were never part of Aspire.Hosting to begin with.

and Aspire.Hosting.PostgreSQL?

Yes, Aspire.Hosting.PostgreSQL is explicitly called out as the example in (2) above. Then the list is the rest that are affected.

eerhardt commented 7 months ago

Finally, I thought that Cognitive Services was a legacy name, and that it was officially rebranded as "Azure AI" now. If that's the case, then I'd argue we should change the name of the new hosting package:

Aspire.Hosting.Azure.* follows the same name as the Azure.Provisioning.* packages. See https://github.com/Azure/azure-sdk-for-net/pull/43045 which is creating Azure.Provisioning.CognitiveServices. My understanding is these names match the corresponding Azure.ResourceManager name - https://www.nuget.org/packages/Azure.ResourceManager.CognitiveServices.

tg-msft commented 7 months ago

For any given service we're going to have (at least) five packages:

That's a lot for customers to wrap their heads around, so positioning them consistently is critical. The rule we're using for Aspire components is Aspire.<ClientLibraryName>. The rule we're using for Azure's Aspire hosting resources is Aspire.Hosting.Azure.<MgmtPlaneSuffix>. We hope it'll be easy for customers to pick up the pattern to make sense of it all.

While we specifically discourage the use of brand or marketing names in modern libraries, many of them like Azure.ResourceManager.CognitiveServices already exist. It would do more harm than good to chase the latest brand names with Aspire packages and diverge from the names Azure is already using (i.e., no matter what we call the packages, you'll still be writing or generating resource ai 'Microsoft.CognitiveServices/accounts@2023-05-01' = { ... } in your bicep).