執行階段套件存放區Runtime package store

從 .NET Core 2.0 開始,可針對目標環境中存在的已知套件集合封裝和部署應用程式。Starting with .NET Core 2.0, it's possible to package and deploy apps against a known set of packages that exist in the target environment. 優點是部署更快、磁碟空間使用量較少,而且啟動效能在某些情況下有所改善。The benefits are faster deployments, lower disk space usage, and improved startup performance in some cases.

這項功能實作為「執行階段套件存放區」,這是套件儲存所在磁碟的目錄 (通常在 macOS/Linux 是 /usr/local/share/dotnet/store,在 Windows 是 C:/Program Files/dotnet/store)。This feature is implemented as a runtime package store, which is a directory on disk where packages are stored (typically at /usr/local/share/dotnet/store on macOS/Linux and C:/Program Files/dotnet/store on Windows). 在此目錄下,有架構和目標 Framework 的子目錄。Under this directory, there are subdirectories for architectures and target frameworks. 檔案配置類似於磁碟上的 NuGet 資產配置方式:The file layout is similar to the way that NuGet assets are laid out on disk:

\dotnet
    \store
        \x64
            \netcoreapp2.0
                \microsoft.applicationinsights
                \microsoft.aspnetcore
                ...
        \x86
            \netcoreapp2.0
                \microsoft.applicationinsights
                \microsoft.aspnetcore
                ...

「目標資訊清單」檔會列出執行階段套件存放區中的套件。A target manifest file lists the packages in the runtime package store. 開發人員可在發佈其應用程式時,以此資訊清單為目標。Developers can target this manifest when publishing their app. 目標資訊清單通常是由目標生產環境的擁有者提供。The target manifest is typically provided by the owner of the targeted production environment.

準備執行階段環境Preparing a runtime environment

執行階段環境的系統管理員可以建置執行階段套件存放區和對應的目標資訊清單,以最佳化應用程式,取得更快的部署和較少的磁碟使用空間。The administrator of a runtime environment can optimize apps for faster deployments and lower disk space use by building a runtime package store and the corresponding target manifest.

第一個步驟是建立「套件存放區資訊清單」,列出撰寫執行階段套件存放區的套件。The first step is to create a package store manifest that lists the packages that compose the runtime package store. 此檔案格式與專案檔格式 (csproj) 相容。This file format is compatible with the project file format (csproj).

<Project Sdk="Microsoft.NET.Sdk">
  <ItemGroup>
    <PackageReference Include="<NUGET_PACKAGE>" Version="<VERSION>" />
    <!-- Include additional packages here -->
  </ItemGroup>
</Project>

範例Example

下例使用套件存放區資訊清單 (packages.csproj) 將 Newtonsoft.JsonMoq 新增至執行階段套件存放區:The following example package store manifest (packages.csproj) is used to add Newtonsoft.Json and Moq to a runtime package store:

<Project Sdk="Microsoft.NET.Sdk">
  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" Version="10.0.3" />
    <PackageReference Include="Moq" Version="4.7.63" />
  </ItemGroup>
</Project>

執行 dotnet store 加上套件存放區資訊清單、執行階段和架構,佈建執行階段套件存放區:Provision the runtime package store by executing dotnet store with the package store manifest, runtime, and framework:

dotnet store --manifest <PATH_TO_MANIFEST_FILE> --runtime <RUNTIME_IDENTIFIER> --framework <FRAMEWORK>

範例Example

dotnet store --manifest packages.csproj --runtime win10-x64 --framework netcoreapp2.0 --framework-version 2.0.0

您可以在命令中重複選項和路徑,將多個目標套件存放區資訊清單路徑傳遞至單一 dotnet store 命令。You can pass multiple target package store manifest paths to a single dotnet store command by repeating the option and path in the command.

根據預設,命令的輸出位在使用者設定檔的 .dotnet/store 子目錄下的套件存放區中。By default, the output of the command is a package store under the .dotnet/store subdirectory of the user's profile. 您可以使用 --output <OUTPUT_DIRECTORY> 選項指定不同的位置。You can specify a different location using the --output <OUTPUT_DIRECTORY> option. 存放區的根目錄包含目標資訊清單 artifact.xml 檔案。The root directory of the store contains a target manifest artifact.xml file. 此檔案可供下載,並可供想要在發行時以此存放區為目標的應用程式作者使用。This file can be made available for download and be used by app authors who want to target this store when publishing.

範例Example

執行上例後,會產生以下 artifact.xml 檔案。The following artifact.xml file is produced after running the previous example. 請注意,Castle.CoreMoq 的相依性,因此會自動包含並出現在 artifacts.xml 資訊清單檔中。Note that Castle.Core is a dependency of Moq, so it's included automatically and appears in the artifacts.xml manifest file.

<StoreArtifacts>
  <Package Id="Newtonsoft.Json" Version="10.0.3" />
  <Package Id="Castle.Core" Version="4.1.0" />
  <Package Id="Moq" Version="4.7.63" />
</StoreArtifacts>

針對目標資訊清單發行應用程式Publishing an app against a target manifest

如果磁碟上有目標資訊清單檔案,您可在使用 dotnet publish 命令發佈應用程式時,指定檔案的路徑:If you have a target manifest file on disk, you specify the path to the file when publishing your app with the dotnet publish command:

dotnet publish --manifest <PATH_TO_MANIFEST_FILE>

範例Example

dotnet publish --manifest manifest.xml

您會將所產生的已發行應用程式,部署到有目標資訊清單所述套件的環境中。You deploy the resulting published app to an environment that has the packages described in the target manifest. 無法這樣做,會導致應用程式無法啟動。Failing to do so results in the app failing to start.

重複選項和路徑 (例如 --manifest manifest1.xml --manifest manifest2.xml),以在發行應用程式時,指定多個目標資訊清單。Specify multiple target manifests when publishing an app by repeating the option and path (for example, --manifest manifest1.xml --manifest manifest2.xml). 當您這樣做時,會針對提供給命令的目標資訊清單檔中指定的套件聯集修剪應用程式。When you do so, the app is trimmed for the union of packages specified in the target manifest files provided to the command.

在專案檔中指定目標資訊清單Specifying target manifests in the project file

dotnet publish 命令指定目標資訊清單的替代方式,是在專案檔中將它們指定為 <TargetManifestFiles> 標記下的以分號分隔的路徑清單。An alternative to specifying target manifests with the dotnet publish command is to specify them in the project file as a semicolon-separated list of paths under a <TargetManifestFiles> tag.

<PropertyGroup>
  <TargetManifestFiles>manifest1.xml;manifest2.xml</TargetManifestFiles>
</PropertyGroup>

只有當應用程式的目標環境為已知時,例如 .NET Core 專案,才在專案檔中指定目標資訊清單。Specify the target manifests in the project file only when the target environment for the app is well-known, such as for .NET Core projects. 這不是開放原始碼專案的情況。This isn't the case for open-source projects. 開放原始碼專案的使用者通常會將它部署到不同的生產環境中。The users of an open-source project typically deploy it to different production environments. 這些生產環境通常會有不同的預先安裝的套件集。These production environments generally have different sets of packages pre-installed. 您不能對這類環境中的目標資訊清單進行假設,因此您應該使用 dotnet publish--manifest 選項。You can't make assumptions about the target manifest in such environments, so you should use the --manifest option of dotnet publish.

ASP.NET Core 隱含存放區ASP.NET Core implicit store

ASP.NET Core 隱含存放區只適用於 ASP.NET Core 2.0。The ASP.NET Core implicit store applies only to ASP.NET Core 2.0. 強烈建議應用程式使用 ASP.NET Core 2.1 和更新版本,這些會使用隱含存放區。We strongly recommend applications use ASP.NET Core 2.1 and later, which does not use the implicit store. ASP.NET Core 2.1 和更新版本會使用共用的架構。ASP.NET Core 2.1 and later use the shared framework.

當應用程式部署為與 Framework 相依的部署 (FDD) 應用程式時,ASP.NET Core 應用程式會以隱含方式使用執行階段套件存放區功能。The runtime package store feature is used implicitly by an ASP.NET Core app when the app is deployed as a framework-dependent deployment (FDD) app. Microsoft.NET.Sdk.Web 中的目標包含參考目標系統上隱含套件存放區的資訊清單。The targets in Microsoft.NET.Sdk.Web include manifests referencing the implicit package store on the target system. 此外,任何相依於 Microsoft.AspNetCore.All 套件的 FDD 應用程式,都會造成已發行的應用程式只包含應用程式及其資產,不包含 Microsoft.AspNetCore.All 中繼套件列出的套件。Additionally, any FDD app that depends on the Microsoft.AspNetCore.All package results in a published app that contains only the app and its assets and not the packages listed in the Microsoft.AspNetCore.All metapackage. 假設這些套件存在於目標系統上。It's assumed that those packages are present on the target system.

安裝 .NET Core SDK 時,執行階段套件存放區會安裝在主機上。The runtime package store is installed on the host when the .NET Core SDK is installed. 其他的安裝程式可能會提供執行階段套件存放區,包括 .NET Core SDK 的 Zip/tarball 安裝、apt-get、Red Hat Yum、.NET Core Windows Server 裝載組合,以及手動的執行階段套件存放區安裝。Other installers may provide the runtime package store, including Zip/tarball installations of the .NET Core SDK, apt-get, Red Hat Yum, the .NET Core Windows Server Hosting bundle, and manual runtime package store installations.

部署與 Framework 相依的部署 (FDD) 應用程式時,請確定目標環境已安裝 .NET Core SDK。When deploying a framework-dependent deployment (FDD) app, make sure that the target environment has the .NET Core SDK installed. 如果應用程式部署到不包含 ASP.NET Core 的環境,您可以像下例一樣在專案檔指定設為 false<PublishWithAspNetCoreTargetManifest>,從隱含的存放區選擇:If the app is deployed to an environment that doesn't include ASP.NET Core, you can opt out of the implicit store by specifying <PublishWithAspNetCoreTargetManifest> set to false in the project file as in the following example:

<PropertyGroup>
  <PublishWithAspNetCoreTargetManifest>false</PublishWithAspNetCoreTargetManifest>
</PropertyGroup>

注意

若為獨立部署 (SCD) 應用程式,假設目標系統不必然包含必要的資訊清單套件。For self-contained deployment (SCD) apps, it's assumed that the target system doesn't necessarily contain the required manifest packages. 因此,SCD 應用程式的 <PublishWithAspNetCoreTargetManifest> 不能設定為 trueTherefore, <PublishWithAspNetCoreTargetManifest> cannot be set to true for an SCD app.

如果您部署的應用程式具有存在於部署中的資訊清單相依性 (組件位於 bin 資料夾),主機對該組件「不會使用」執行階段套件存放區。If you deploy an application with a manifest dependency that's present in the deployment (the assembly is present in the bin folder), the runtime package store isn't used on the host for that assembly. 無論主機的執行階段套件存放區是否有 bin 資料夾組件,都使用它。The bin folder assembly is used regardless of its presence in the runtime package store on the host.

資訊清單中指示的相依性版本,必須符合執行階段套件存放區中的相依性版本。The version of the dependency indicated in the manifest must match the version of the dependency in the runtime package store. 如果目標資訊清單中的相依性版本與執行階段套件存放區的版本不相符,而應用程式的部署中不包含必要的套件版本,則應用程式無法啟動。If you have a version mismatch between the dependency in the target manifest and the version that exists in the runtime package store and the app doesn't include the required version of the package in its deployment, the app fails to start. 例外狀況包含目標資訊清單的名稱,為執行階段套件存放區組件所稱呼的名稱,有利於針對不符合進行疑難排解。The exception includes the name of the target manifest that called for the runtime package store assembly, which helps you troubleshoot the mismatch.

於發行時「修剪」部署,已發行的輸出只保留您指定的資訊清單套件特定版本。When the deployment is trimmed on publish, only the specific versions of the manifest packages you indicate are withheld from the published output. 主機必須要有指定版本的套件,應用程式才能啟動。The packages at the versions indicated must be present on the host for the app to start.

另請參閱See also