diff --git a/aspnetcore/fundamentals/metapackage-app.md b/aspnetcore/fundamentals/metapackage-app.md new file mode 100644 index 000000000000..cdf5a00ea755 --- /dev/null +++ b/aspnetcore/fundamentals/metapackage-app.md @@ -0,0 +1,59 @@ +--- +title: Microsoft.AspNetCore.App metapackage for ASP.NET Core 2.1 and later +author: Rick-Anderson +description: The Microsoft.AspNetCore.App metapackage includes all supported ASP.NET Core and Entity Framework Core packages. +manager: wpickett +monikerRange: '>= aspnetcore-2.1' +ms.author: riande +ms.date: 09/20/2017 +ms.prod: asp.net-core +ms.technology: aspnet +ms.topic: article +uid: fundamentals/metapackage-app +--- +# Microsoft.AspNetCore.App metapackage for ASP.NET Core 2.1 + +This feature requires ASP.NET Core 2.1 and later targeting .NET Core 2.1 and later. + +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](https://www.nuget.org/packages/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). +* Includes all supported packages by the Entity Framework Core team except those that contain third-party dependencies (other than those previously mentioned). + +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 later and Entity Framework Core 2.1 and later 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. + +Using the `Microsoft.AspNetCore.App` metapackage provides version restrictions that protect your app: + +* If a package is included that has a transitive (not direct) dependency on a package in `Microsoft.AspNetCore.App`, and those version numbers differ, NuGet will generate an error. +* 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 ASP.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 ASP.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). + +The following *.csproj* project file references the `Microsoft.AspNetCore.App` metapackage for ASP.NET Core: + +```xml + + + + netcoreapp2.1 + + + + + + + + +``` + +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 specified by the SDK and not explicitly setting the version number on the package reference. You can leave a GitHub comment at [Discussion for the Microsoft.AspNetCore.App implicit version](https://github.com/aspnet/Docs/issues/6430). + +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 bundled 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). + +If your application previously used `Microsoft.AspNetCore.All`, see [Migrating from Microsoft.AspNetCore.All to Microsoft.AspNetCore.App](xref:fundamentals/metapackage#migrate). \ No newline at end of file diff --git a/aspnetcore/fundamentals/metapackage.md b/aspnetcore/fundamentals/metapackage.md index 213a224f0127..928b909209c9 100644 --- a/aspnetcore/fundamentals/metapackage.md +++ b/aspnetcore/fundamentals/metapackage.md @@ -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 and later author: Rick-Anderson description: The Microsoft.AspNetCore.All metapackage includes all supported ASP.NET Core and Entity Framework Core packages, along with their dependencies. manager: wpickett -monikerRange: '= aspnetcore-2.0' +monikerRange: '>= aspnetcore-2.0' ms.author: riande ms.date: 09/20/2017 ms.prod: asp.net-core @@ -12,7 +12,10 @@ ms.topic: article uid: fundamentals/metapackage --- -# Microsoft.AspNetCore.All metapackage for ASP.NET Core 2.x +# Microsoft.AspNetCore.All metapackage for ASP.NET Core 2.0 + +> [!NOTE] +> We recommend applications targeting ASP.NET Core 2.1 and later use the [Microsoft.AspNetCore.App](xref:fundamentals/metapackage-all) rather than this package. See [Migrating from Microsoft.AspNetCore.All to Microsoft.AspNetCore.App](#migrate) in this article. This feature requires ASP.NET Core 2.x targeting .NET Core 2.x. @@ -24,7 +27,7 @@ The [Microsoft.AspNetCore.All](https://www.nuget.org/packages/Microsoft.AspNetCo All the features of ASP.NET Core 2.x and Entity Framework Core 2.x are included in the `Microsoft.AspNetCore.All` package. The default project templates targeting ASP.NET Core 2.0 use this package. -The version number of the `Microsoft.AspNetCore.All` metapackage represents the ASP.NET Core version and Entity Framework Core version (aligned with the .NET Core version). +The version number of the `Microsoft.AspNetCore.All` metapackage represents the ASP.NET Core version and Entity Framework Core version. Applications that use the `Microsoft.AspNetCore.All` metapackage automatically take advantage of the [.NET Core Runtime Store](https://docs.microsoft.com/dotnet/core/deploying/runtime-store). The Runtime Store contains all the runtime assets needed to run ASP.NET Core 2.x applications. When you use the `Microsoft.AspNetCore.All` metapackage, **no** assets from the referenced ASP.NET Core NuGet packages are deployed with the application — the .NET Core Runtime Store contains these assets. The assets in the Runtime Store are precompiled to improve application startup time. @@ -33,3 +36,31 @@ You can use the package trimming process to remove packages that you don't use. The following *.csproj* file references the `Microsoft.AspNetCore.All` metapackage for ASP.NET Core: [!code-xml[](../mvc/views/view-compilation/sample/MvcRazorCompileOnPublish2.csproj?highlight=9)] + + +## Migrating from Microsoft.AspNetCore.All to Microsoft.AspNetCore.App + +The following packages are included in `Microsoft.AspNetCore.All` but not the `Microsoft.AspNetCore.App` package. + +* `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` + +To move from `Microsoft.AspNetCore.All` to `Microsoft.AspNetCore.App`, if your app uses any APIs from the above packages, or packages brought in by those packages, add references to those packages in your project. + +Any dependencies of the preceding packages that otherwise aren't dependencies of `Microsoft.AspNetCore.App` are not included implicitly. For example: + +* `StackExchange.Redis` as a dependency of `Microsoft.Extensions.Caching.Redis` +* `Microsoft.ApplicationInsights` as a dependency of `Microsoft.AspNetCore.ApplicationInsights.HostingStartup` \ No newline at end of file