Microsoft.AspNetCore.App metapackage #6069
Conversation
|
@glennc please review or assign someone. I opened Document shared framework. I'll link to that doc when it's written. In the mean time do you want me to explain the shared framework layout, etc? |
|
@glennc please review or assign someone. |
| ms.prod: asp.net-core | ||
| ms.technology: aspnet | ||
| ms.topic: article | ||
| uid: fundamentals/metapackage-all |
There was a problem hiding this comment.
@Rick-Anderson Did you mean "-app" here?
|
@danroth27 @glennc Fowler requested a "How to upgrade from 2.0 to 2.1" doc. Is there anymore to that than what's in this doc? We need to get this published ASAP, lots of customers have M.A.App and M.A.All questions. |
| @@ -0,0 +1,58 @@ | |||
| --- | |||
| title: Microsoft.AspNetCore.App metapackage for ASP.NET Core 2.x and later | |||
There was a problem hiding this comment.
The Microsoft.AspNetCore.App exists only for 2.1 and later. It does not exist in 2.0
| --- | ||
| title: Microsoft.AspNetCore.App metapackage for ASP.NET Core 2.x and later | ||
| author: Rick-Anderson | ||
| description: The Microsoft.AspNetCore.App metapackage includes all supported ASP.NET Core and Entity Framework Core packages, along with their dependencies. |
There was a problem hiding this comment.
Technically not true since we specifically add Microsoft.AspNetCore.App to remove supported packages that had third party dependencies.
|
|
||
| The [Microsoft.AspNetCore.App](https://www.nuget.org/packages/Microsoft.AspNetCore.App) metapackage for ASP.NET Core includes: | ||
|
|
||
| * All supported packages by the ASP.NET Core team. |
There was a problem hiding this comment.
This phrasing is not accurate since we don't include packages that contain third party dependencies like Redis.
There was a problem hiding this comment.
@JunTaoLuo can you suggest better wording.
Most of the supported packages by the ASP.NET Core team.
How about
All supported packages by the ASP.NET Core team except a few that that contain third party dependencies like Redis.
There was a problem hiding this comment.
All supported packages without third party dependencies of the ASP.NET Core team.
|
|
||
| All the features of ASP.NET Core 2.1 and later and Entity Framework Core 2.1 and later are included in the `Microsoft.AspNetCore.App` package. The default project templates targeting ASP.NET Core 2.1 and later use this package. We recommend applications targeting ASP.NET Core 2.1+ and Entity Framework Core 2.1+ use the `Microsoft.AspNetCore.App` package. | ||
|
|
||
| The version number of the `Microsoft.AspNetCore.App` metapackage represents the ASP.NET Core version and Entity Framework Core version (aligned with the .NET Core version). |
There was a problem hiding this comment.
I'm not sure if we can claim this. Technically aspnetcore and .net core are independently versioned. Most of the time, we will be aligned but this is not a promise going forward.
There was a problem hiding this comment.
The ASP.NET Core version is currently aligned with the .NET Core version, and we hope to continue version alignment in the future.
There was a problem hiding this comment.
As much as this is likely the case for the majority of the time, I don't know if we can make this promise. There may be cases where the runtime is not updating but aspnetcore needs to ship an update in which case the versions will no longer align. Unless we promise to rev the entire stack any time there is a change anywhere. I'm not sure that's the model we are committed to adopting.
| @@ -1,9 +1,9 @@ | |||
| --- | |||
| title: Microsoft.AspNetCore.All metapackage for ASP.NET Core 2.x and later | |||
| title: Microsoft.AspNetCore.All metapackage for ASP.NET Core 2.0 | |||
There was a problem hiding this comment.
We have the .All package for 2.1 as well so this should be 2.x.
| * Other packages added to your app cannot change the version of packages included in `Microsoft.AspNetCore.App`. | ||
| * Version consistency ensures a reliable experience. `Microsoft.AspNetCore.App` was designed to prevent untested version combinations of related bits being used together in the same app. | ||
|
|
||
| Applications that use the `Microsoft.AspNetCore.App` metapackage automatically take advantage of the .NET Core shared framework. When you use the `Microsoft.AspNetCore.App` metapackage, **no** assets from the referenced ASP.NET Core NuGet packages are deployed with the application — the .NET Core shared framework contains these assets. The assets in the shared framework are precompiled to improve application startup time. For more information, see "shared framework" in [.NET Core distribution packaging](/dotnet/core/build/distribution-packaging). |
There was a problem hiding this comment.
The assets are contained in the ASP.NET Core shared framework not the .NET Core shared framework.
|
|
||
| ``` | ||
|
|
||
| The preceding markup doesn't specify a version number for the `Microsoft.AspNetCore.App` NuGet package. The ASP.NET Core 2.1+ templates generate this markup without a version number. Not specifying a version is convent early in development when you want the latest version. Most teams will add a version number when deploying the app to ensure that development, test, and production are all using the same version. With a fixed version number, updates to the host will not cause the app to use a newer version of the NuGet package. |
There was a problem hiding this comment.
convent? Word choice is a little confusing. Also, even while deploying an app, we don't recommend users to add a version number. We want the version number to remain implicit in all scenarios. The shared framework roll forward mechanism will always run the app on the latest version of the installed shared framework. To guarantee the same version is used in dev, test, and production, you'll need to ensure the same version of the shared framework is installed in all environments.
| ::: moniker range=">= aspnetcore-2.1" | ||
| # Microsoft.AspNetCore.All metapackage for ASP.NET Core 2.1 and later version range locking | ||
|
|
||
| `Microsoft.AspNetCore.All` 2.1 and later specifies package dependency ranges. The package dependency ranges ensure that only the excact version specified for each dependency is allowed. Any other dependency that attempts to lift a version for a component beyond what is specified in the meta-package will result in a NuGet warning, which the Microsoft.NET.Sdk will elevate to an error by default. |
There was a problem hiding this comment.
This is not true, there is no version locking in Microsoft.AspNetCore.All. Version locking is only added to Microsoft.AspNetCore.All.
|
|
||
| The following packages are direct dependencies of `Microsoft.AspNetCore.All` but not the `Microsoft.AspNetCore.App` package. | ||
|
|
||
| * Microsoft.Data.Sqlite |
There was a problem hiding this comment.
How did you generate this list?
I took a diff of the packages and these are the extra packages in .All and not in .App.
Microsoft.AspNetCore.ApplicationInsights.HostingStartup
Microsoft.AspNetCore.AzureAppServices.HostingStartup
Microsoft.AspNetCore.AzureAppServicesIntegration
Microsoft.AspNetCore.DataProtection.AzureKeyVault
Microsoft.AspNetCore.DataProtection.AzureStorage
Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv
Microsoft.AspNetCore.SignalR.Redis
Microsoft.Data.Sqlite
Microsoft.Data.Sqlite.Core
Microsoft.EntityFrameworkCore.Sqlite
Microsoft.EntityFrameworkCore.Sqlite.Core
Microsoft.Extensions.Caching.Redis
Microsoft.Extensions.Configuration.AzureKeyVault
Microsoft.Extensions.Logging.AzureAppServices
Microsoft.VisualStudio.Web.BrowserLink
A few things to note. Microsoft.AspNetCore.Identity.Service.AzureKeyVault is not a shipping package and Microsoft.AspNetCore.AzureKeyVault.HostingStartup only exists in 2.0 and is not (and was never) included in the .All metapackage.
| The [Microsoft.AspNetCore.App](https://www.nuget.org/packages/Microsoft.AspNetCore.App) metapackage for ASP.NET Core includes: | ||
|
|
||
| * All supported packages by the ASP.NET Core team except those that contain third party dependencies. | ||
| * All supported packages by the Entity Framework Core. |
There was a problem hiding this comment.
The same clarification applies to EF packages. We should add "exception those that contain third party dependencies" or something similar. Though I don't like this wording either; allow me to clarify.
We have removed most of the third party dependencies in the .App package. However, due to a variety of reasons, there are three exceptions to the rule. We continue to use Json.NET, Remotion.Linq and IX-Async packages in the .App metapackage.
I think it may be better to phrase by listing the three third party dependencies first. Then "All supported packages by the ASP.NET Core team exception those containing third party dependencies other than the three previously mentioned." And the same for the EF packages.
|
|
||
| * All supported packages by the ASP.NET Core team except those that contain third party dependencies. | ||
| * All supported packages by the Entity Framework Core. | ||
| * Internal dependencies used by ASP.NET Core and Entity Framework Core. |
There was a problem hiding this comment.
What do you mean by this? What are the internal dependencies you are referring to?
| * All supported packages by the ASP.NET Core team except those that contain third party dependencies. | ||
| * All supported packages by the Entity Framework Core. | ||
| * Internal dependencies used by ASP.NET Core and Entity Framework Core. | ||
| * 3rd-party dependencies used by ASP.NET Core and Entity Framework Core deemed necessary to ensure the major frameworks features function. |
There was a problem hiding this comment.
Let's remove this line to reduce the confusion.
| * Internal dependencies used by ASP.NET Core and Entity Framework Core. | ||
| * 3rd-party dependencies used by ASP.NET Core and Entity Framework Core deemed necessary to ensure the major frameworks features function. | ||
|
|
||
| All the features of ASP.NET Core 2.1 and later and Entity Framework Core 2.1 and later are included in the `Microsoft.AspNetCore.App` package. The default project templates targeting ASP.NET Core 2.1 and later use this package. We recommend applications targeting ASP.NET Core 2.1+ and Entity Framework Core 2.1+ use the `Microsoft.AspNetCore.App` package. |
There was a problem hiding this comment.
Nit: We are switching between "2.1 and later" and "2.1+". We should just pick a convention and stick to it.
There was a problem hiding this comment.
The style manual usually uses "or later" ... there's one spot tho where it references the phrase "and later." AFAIK, we've been using "or later" here and in the .NET Core docs.
There was a problem hiding this comment.
2.1 and later gets tedious when used multiple times in a sentence/paragraph. We can't use 2.1+ globally.
There was a problem hiding this comment.
Truly, they're pretty vague on it. They just don't like "higher" and "greater" for versions. I bet they don't care all that much about the plus sign (or they forgot to mention it 😈).
|
|
||
| Using the the `Microsoft.AspNetCore.App` metapackage provides version restrictions that protect your app: | ||
|
|
||
| * Other packages added to your app cannot change the version of packages included in `Microsoft.AspNetCore.App`. |
There was a problem hiding this comment.
This is a little more nuanced.
First, if you add a direct reference to a package that's included in .App, you will be able to override the version number.
Second, we don't technically prevent you from adding a package that has a transitive (not direct) dependency on a package that is included in .App. In this case, nuget will produce an error. The phrasing suggests, to me at least, that we have additional consolidation logic to set all packages to the version that's specified in .App which is not accurate.
|
|
||
| We recommend not specifying the version number. By not specifying the version, the shared framework roll forward mechanism will run the app on the latest version of the installed shared framework. To guarantee the same version is used in development, test, and production, ensure the same version of the shared framework is installed in all environments. | ||
|
|
||
| Developers can choose to specify a version number to guarantee the same version is used in development, test, and production. With a fixed version number, updates to the hosts shared framework will not cause the app to use a newer version of the `Microsoft.AspNetCore.App` package. |
There was a problem hiding this comment.
This is also inaccurate. Even if the user specifies an explicit version number, they will only ensure that the package references, intellisense, etc are the same at compile time in all environments. The shared framework roll-forward will always roll forward to the latest patch. Even if you pick 2.1.1, but 2.1.3 is installed, you will run on 2.1.3. To disable roll forward (patch and/or minor) you'll need to specify the options on the dotnet host: see Settings to control behavior https://github.com/dotnet/core-setup/blob/master/Documentation/design-docs/roll-forward-on-no-candidate-fx.md
|
|
||
| Developers can choose to specify a version number to guarantee the same version is used in development, test, and production. With a fixed version number, updates to the hosts shared framework will not cause the app to use a newer version of the `Microsoft.AspNetCore.App` package. | ||
|
|
||
| If your application previously used `Migrating from Microsoft.AspNetCore.All`, see [Migrating from Microsoft.AspNetCore.All to Microsoft.AspNetCore.App](xref:fundamentals/metapackage#migrate). |
There was a problem hiding this comment.
previously used Migrating from Microsoft.AspNetCore.All? You mean previously used Microsoft.AspNetCore.All?
| @@ -12,7 +12,10 @@ ms.topic: article | |||
| uid: fundamentals/metapackage | |||
There was a problem hiding this comment.
No need to change the file name and the UID.
|
|
||
| All the features of ASP.NET Core 2.1 and later and Entity Framework Core 2.1 and later are included in the `Microsoft.AspNetCore.App` package. The default project templates targeting ASP.NET Core 2.1 and later use this package. We recommend applications targeting ASP.NET Core 2.1+ and Entity Framework Core 2.1+ use the `Microsoft.AspNetCore.App` package. | ||
|
|
||
| The version number of the `Microsoft.AspNetCore.App` metapackage represents the ASP.NET Core version and Entity Framework Core version. The ASP.NET Core version is currently aligned with the .NET Core version, and we hope to continue version alignment in the future. |
There was a problem hiding this comment.
The reason I mentioned the independence between the aspnetcore versions and the .net versions is because in 2.0 aspnet metapackage is no longer aligned with .net. i.e. the latest patch uses aspnetcore 2.0.8 and .net core 2.0.7. You would want to update the same section in the .All doc as well.
| <a name="migrate"></a> | ||
| ## Migrating from Microsoft.AspNetCore.All to Microsoft.AspNetCore.App | ||
|
|
||
| The following packages included in `Microsoft.AspNetCore.All` but not the `Microsoft.AspNetCore.App` package. |
|
@JunTaoLuo I'm sure I didn't get the section on versioning. Can you do one of the following rather than writing the corrections?
|
|
|
||
| The [Microsoft.AspNetCore.App](https://www.nuget.org/packages/Microsoft.AspNetCore.App) metapackage for ASP.NET Core: | ||
|
|
||
| * Does not include third-party dependencies except for [Json.NET](https://www.nuget.org/packages/Newtonsoft.Json/), [Remotion.Linq, and [IX-Async](https://www.nuget.org/packages/System.Interactive.Async/). These 3rd-party dependencies are deemed necessary to ensure the major frameworks features function. |
There was a problem hiding this comment.
Remotion.Linq link seems broken
|
|
||
| * Does not include third-party dependencies except for [Json.NET](https://www.nuget.org/packages/Newtonsoft.Json/), [Remotion.Linq, and [IX-Async](https://www.nuget.org/packages/System.Interactive.Async/). These 3rd-party dependencies are deemed necessary to ensure the major frameworks features function. | ||
| * Includes all supported packages by the ASP.NET Core team except those that contain third-party dependencies (other than those previously mentioned). | ||
| * All supported packages by the Entity Framework Core team except those that contain third-party dependencies (other than those previously mentioned). |
There was a problem hiding this comment.
nit: Includes all (for consistency)
|
|
||
| ``` | ||
|
|
||
| The preceding markup doesn't specify a version number for the `Microsoft.AspNetCore.App` NuGet package. The ASP.NET Core 2.1 and later templates generate this markup without a version number. When the version is not specified, the implicit version is used: |
There was a problem hiding this comment.
Tried to clean up this section a bit.
The preceding markup represents a typical ASP.NET Core 2.1 and later template. It doesn't specify a version number for the `Microsoft.AspNetCore.App` package reference. When the version is not specified, an implicit version is specified by the SDK, that is, `Microsoft.NET.Sdk.Web`. We recommend relying on the implicit version specifyed by the SDK and not explictly setting the version number on the package reference.
The implicit version is set to `major.minor.0` for portable apps. The shared framework roll-forward mechanism will run the app on the latest compatible version among the installed shared frameworks. To guarantee the same version is used in development, test, and production, ensure the same version of the shared framework is installed in all environments. For self contained apps, the implicit version number is set to the `major.minor.patch` of the shared framework bunlded in the installed SDK.
Specifying a version number on the `Microsoft.AspNetCore.App` reference does **not** guarantee that version of the shared framework will be chosen. For example, suppose version "2.1.1" is specified, but "2.1.3" is installed. In that case, the app will use "2.1.3". Although not recommended, you can disable roll forward (patch and/or minor). For more information regarding dotnet host roll forward and how to configure its behavior, see [dotnet host roll forward](https://github.com/dotnet/core-setup/blob/master/Documentation/design-docs/roll-forward-on-no-candidate-fx.md).
|
@JunTaoLuo awesome rewrite. I made one minor wordsmith change. OK to merge? |
|
@JunTaoLuo I added You can leave a GitHub comment at Discussion for the Microsoft.AspNetCore.App implicit version. I know this is going to be hotly debated by customers. Let me know if that's OK or you'd rather have the discussion in the MVC repo. |
|
aspnet/Home would work fine. Let's make sure to put it in the Discussions milestone. edit to clarify: We create posts on the Announcements repo to tell customers what is coming, what is changing etc.. We lock those posts so that we can constrain the amount of notifications go out of Announcements repo. We don't want to spam people who are just expecting announcements from the ASP.NET team. For almost all announcements of this nature, we file a bug in Home or some other repo for discussing that particular announcement post. |
Fixes #5884
M.A.App review
M.A.ALL review