Update documentation on the various package archive formats (#1324)
This commit is contained in:
Nate McMaster
GitHub
parent
d3dcf1cb30
commit
16164689dc
|
|
@ -1,54 +0,0 @@
|
|||
Fallback Package Cache (LZMA)
|
||||
=============================
|
||||
|
||||
The fallback package cache (commonly called the LZMA) is a set of NuGet packages that are bundled in the .NET Core SDK installers.
|
||||
The LZMA is a compressed file format, similar to a .zip.
|
||||
On first use or on install, the .NET Core CLI will expand this LZMA file, extracting the packages inside to %DOTNET_INSTALL_DIR%/sdk/NuGetFallbackFolder.
|
||||
|
||||
## Requirements
|
||||
|
||||
The following requirements are used to determine which packages go into the fallback package cache:
|
||||
|
||||
- A user should be able to restore the following templates and only use packages from the offline cache:
|
||||
- `dotnet new console`
|
||||
- `dotnet new library`
|
||||
- `dotnet new web`
|
||||
- `dotnet new razor`
|
||||
- `dotnet new mvc`
|
||||
|
||||
The following packages are NOT included in the offline cache.
|
||||
- Packages required for standalone publishing, aka projects that set a Runtime Identifier during restore
|
||||
- Packages required for F# and VB templates
|
||||
- Packages required for Visual Studio code generation in ASP.NET Core projects
|
||||
- Packages required to restore .NET Framework projects
|
||||
- Packages required to restore test projects, such as xunit, MSTest, NUnit
|
||||
|
||||
The result of this typically means including the transitive graph of the following packages:
|
||||
|
||||
- Packages that match bundled runtimes
|
||||
- Microsoft.NETCore.App
|
||||
- Microsoft.AspNetCore.App
|
||||
- Microsoft.AspNetCore.All
|
||||
- Packages that Microsoft.NET.Sdk adds implicitly
|
||||
- Microsoft.NETCore.App
|
||||
- NETStandard.Library
|
||||
- Packages that are a PackageReference/DotNetCliToolReference in basic ASP.NET Core templates. In addition to packages above, this typically includes:
|
||||
- Microsoft.EntityFrameworkCore.Tools{.DotNet}
|
||||
- Microsoft.VisualStudio.Web.CodeGeneration.Design
|
||||
- Microsoft.VisualStudio.Web.BrowserLink
|
||||
|
||||
### Example
|
||||
|
||||
Given the following parameters:
|
||||
- LatestNETCoreAppTFM = netcoreapp2.1
|
||||
- DefaultRuntimeVersion = 2.1
|
||||
- BundledRuntimeVersion = 2.1.8
|
||||
- BundledAspNetRuntimeVersion = 2.1.7
|
||||
- LatestNETStandardLibraryTFM = netstandard2.0
|
||||
- BundledNETStandardLibraryVersion = 2.0.1
|
||||
|
||||
The LZMA should contain
|
||||
- Microsoft.NETCore.App/2.1.0 + netcoreapp2.1 dependencies (Microsoft.NET.Sdk will implicitly reference "2.1", which NuGet to 2.1.0)
|
||||
- Microsoft.NETCore.App/2.1.8 + netcoreapp2.1 dependencies (Matches the runtime in shared/Microsoft.NETCore.App/2.1.8/)
|
||||
- Microsoft.AspNetCore.All/2.1.7 + netcoreapp2.1 dependencies (Matches the runtime in shared/Microsoft.AspNetCore.All/2.1.7/)
|
||||
- NETStandard.Library/2.0.1 + netstandard2.0 dependencies (Microsoft.NET.Sdk will implicitly reference "2.0.1")
|
||||
|
|
@ -0,0 +1,68 @@
|
|||
Package Archives
|
||||
================
|
||||
|
||||
This repo builds multiple package archives which contain a NuGet fallback folder (also known as the fallback or offline package cache). The fallback folder is a set of NuGet packages that is bundled in the .NET Core SDK installers and available in Azure Web App service.
|
||||
|
||||
Package archives are available in four varieties.
|
||||
|
||||
* **LZMA** - `nuGetPackagesArchive-$(Version).lzma` - The LZMA is a compressed file format, similar to a .zip. On first use or on install, the .NET Core CLI will expand this LZMA file, extracting the packages inside to %DOTNET_INSTALL_DIR%/sdk/NuGetFallbackFolder. This contains all NuGet packages and their complete contents.
|
||||
* **ci-server** - `nuGetPackagesArchive-ci-server-$(Version).zip` - this archive is optimized for CI server environments. It contains the same contents as the LZMA, but trimmed of xml docs (these are only required for IDEs) and .nupkg files (not required for NuGet as for the 2.0 SDK).
|
||||
* **ci-server-patch** - `nuGetPackagesArchive-ci-server-$(Version).patch.zip` - this archive is the same as the ci-server archive, but each release is incremental - i.e. it does not bundle files that were present in a previous ci-server archive release. This can be used by first starting with a baseline `nuGetPackagesArchive-ci-server-$(Version).zip` and then applying the `.patch.zip` version for subsequent updates.
|
||||
* **ci-server-compat-patch** - `nuGetPackagesArchive-ci-server-compat-$(Version).patch.zip` - similar to the ci-server-patch archive, but this includes .nupkg files to satisfy CI environments that may have older NuGet clients.
|
||||
|
||||
These archives are built using the projects in [src/PackageArchive/Archive.\*/](/src/PackageArchive/).
|
||||
|
||||
## Using a fallback folder
|
||||
|
||||
NuGet restore takes a list of fallback folders in the MSBuild property `RestoreAdditionalProjectFallbackFolders`. Unlike a folder restore source, restore will not copy the packages from a fallback folder into the global NuGet cache.
|
||||
|
||||
By default, the .NET Core SDK adds `$(DotNetInstallRoot)/sdk/NuGetFallbackFolder/` to this list. The .NET Core CLI expands its bundled `nuGetPackagesArchive.lzma` file into this location on first use or when the installers run. (See [Microsoft.NET.NuGetOfflineCache.targets](https://github.com/dotnet/sdk/blob/v2.1.300/src/Tasks/Microsoft.NET.Build.Tasks/targets/Microsoft.NET.NuGetOfflineCache.targets)).
|
||||
|
||||
## Scenarios
|
||||
|
||||
The following scenarios are used to determine which packages go into the fallback package cache.
|
||||
These requirements are formalized as project files in [src/PackageArchive/Scenario.\*/](/src/PackageArchive/).
|
||||
|
||||
- A user should be able to restore the following templates and only use packages from the offline cache:
|
||||
- `dotnet new console`
|
||||
- `dotnet new library`
|
||||
- `dotnet new web`
|
||||
- `dotnet new razor`
|
||||
- `dotnet new mvc`
|
||||
|
||||
The following packages are NOT included in the offline cache.
|
||||
- Packages required for standalone publishing, aka projects that set a Runtime Identifier during restore
|
||||
- Packages required for F# and VB templates
|
||||
- Packages required for Visual Studio code generation in ASP.NET Core projects
|
||||
- Packages required to restore .NET Framework projects
|
||||
- Packages required to restore test projects, such as xunit, MSTest, NUnit
|
||||
|
||||
The result of this typically means including the transitive graph of the following packages:
|
||||
|
||||
- Packages that match bundled runtimes
|
||||
- Microsoft.NETCore.App
|
||||
- Microsoft.AspNetCore.App
|
||||
- Microsoft.AspNetCore.All
|
||||
- Packages that Microsoft.NET.Sdk adds implicitly
|
||||
- Microsoft.NETCore.App
|
||||
- NETStandard.Library
|
||||
- Packages that are a PackageReference/DotNetCliToolReference in basic ASP.NET Core templates. In addition to packages above, this typically includes:
|
||||
- Microsoft.EntityFrameworkCore.Tools{.DotNet}
|
||||
- Microsoft.VisualStudio.Web.CodeGeneration.Design
|
||||
- Microsoft.VisualStudio.Web.BrowserLink
|
||||
|
||||
### Example
|
||||
|
||||
Given the following parameters:
|
||||
- LatestNETCoreAppTFM = netcoreapp2.1
|
||||
- DefaultRuntimeVersion = 2.1
|
||||
- BundledRuntimeVersion = 2.1.8
|
||||
- BundledAspNetRuntimeVersion = 2.1.7
|
||||
- LatestNETStandardLibraryTFM = netstandard2.0
|
||||
- BundledNETStandardLibraryVersion = 2.0.1
|
||||
|
||||
The LZMA should contain
|
||||
- Microsoft.NETCore.App/2.1.0 + netcoreapp2.1 dependencies (Microsoft.NET.Sdk will implicitly reference "2.1", which NuGet to 2.1.0)
|
||||
- Microsoft.NETCore.App/2.1.8 + netcoreapp2.1 dependencies (Matches the runtime in shared/Microsoft.NETCore.App/2.1.8/)
|
||||
- Microsoft.AspNetCore.All/2.1.7 + netcoreapp2.1 dependencies (Matches the runtime in shared/Microsoft.AspNetCore.All/2.1.7/)
|
||||
- NETStandard.Library/2.0.1 + netstandard2.0 dependencies (Microsoft.NET.Sdk will implicitly reference "2.0.1")
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
PackageArchive
|
||||
==============
|
||||
|
||||
See [docs/PackageArchives.md](/docs/PackageArchives.md) for details.
|
||||
|
||||
See [ZipManifestGenerator](/src/PackageArchive/ZipManifestGenerator) for instructions on updating the build for new releases.
|
||||
Loading…
Reference in New Issue