閱讀英文

共用方式為


NuGet 套件和還原為 MSBuild 目標

NuGet 4.0+

使用 PackageReference 格式, NuGet 4.0+ 可以直接將所有指令清單元數據儲存在專案檔內,而不是使用不同的.nuspec檔案。

MSBuild 15.1+ 也是具有 和 restore 目標的一流MSBuild公民pack,NuGet如下所述。 這些目標可讓您像處理任何其他MSBuild工作或目標一樣使用NuGet。 如需使用 建立NuGet封裝的指示,請參閱使用 MSBuild建立NuGetMSBuild套件。 (針對NuGet3.x 和更早版本,您可以改為透過 NuGet CLI 使用套件還原命令。

目標組建順序

由於 packrestore 是 MSBuild 目標,因此您可以存取它們來增強您的工作流程。 例如,假設您想要在封裝套件之後將套件複製到網路共用。 做法是在專案檔中新增下列項目:

<Target Name="CopyPackage" AfterTargets="Pack">
  <Copy
    SourceFiles="$(OutputPath)..\$(PackageId).$(PackageVersion).nupkg"
    DestinationFolder="\\myshare\packageshare\"
    />
</Target>

同樣地,您可以撰寫工作MSBuild、撰寫自己的目標,並在工作中取用NuGetMSBuild屬性。

注意

$(OutputPath) 是相對的,而且預期您正在從專案根目錄執行命令。

封裝目標

針對使用 格式的 PackageReference .NET 專案,使用 msbuild -t:pack 從專案檔繪製輸入,以用於建立 NuGet 套件。

下表描述 MSBuild 可新增至第一 <PropertyGroup> 個節點內項目檔的屬性。 以滑鼠右鍵按一下專案,然後選取操作功能表上的 [編輯 {project_name}],即可在 Visual Studio 2017 和更新版本中輕鬆地進行這些編輯。 為了方便起見,數據表是由檔案中的.nuspec對等屬性所組織。

注意

Owners不支援 來自 .nuspec MSBuild的和 Summary 屬性。

屬性/nuspec 值 MSBuild 屬性 預設 備註
Id PackageId $(AssemblyName) MSBuild 中的 $(AssemblyName)
Version PackageVersion 版本 這與 semver 相容,例如 1.0.01.0.0-beta1.0.0-beta-00345。 如果未設定,則預設為 Version
VersionPrefix VersionPrefix empty 設定 PackageVersion 覆寫 VersionPrefix
VersionSuffix VersionSuffix empty 設定 PackageVersion 覆寫 VersionSuffix
Authors Authors 目前使用者的使用者名稱 以分號分隔的套件作者清單,符合 .org 上的nuget配置檔名稱。這些會顯示在 .org 上的NuGetnuget資源庫中,並用來由相同的作者交叉參考套件。
Owners N/A 不存在於 nuspec
Title Title $(PackageId) 套件的易記標題,通常會在UI中顯示為 .org和nugetVisual Studio中的 封裝管理員。
Description Description "Package Description" 組件的完整描述。 如果未 PackageDescription 指定,則這個屬性也會當做封裝的描述使用。
Copyright Copyright empty 套件的著作權詳細資料。
RequireLicenseAcceptance PackageRequireLicenseAcceptance false 布林值,指定在安裝套件時,用戶端是否必須提示取用者接受套件授權。
license PackageLicenseExpression empty 對應至 <license type="expression">。 請參閱 封裝授權表達式或授權檔
license PackageLicenseFile empty 如果您使用自定義授權或尚未指派 SPDX 識別碼的授權,則套件內授權檔案的路徑。 您必須明確封裝參考的授權檔案。 對應至 <license type="file">。 請參閱 封裝授權表達式或授權檔
LicenseUrl PackageLicenseUrl empty PackageLicenseUrl 已被取代。 請改用 PackageLicenseExpressionPackageLicenseFile
ProjectUrl PackageProjectUrl empty
Icon PackageIcon empty 封裝中要做為封裝圖示的影像路徑。 您必須明確地封裝參考的圖示圖像檔。 如需詳細資訊,請參閱 封裝圖示圖像檔 案和 icon 元數據
IconUrl PackageIconUrl empty 已淘汰 PackageIconUrl 而改用 PackageIcon。 不過,為了獲得最佳的下層體驗,除了 之外,您也應該指定 PackageIconUrl PackageIcon
Readme PackageReadmeFile empty 您必須明確地封裝參考的自述檔。
Tags PackageTags empty 以分號分隔的標記清單,用以指定套件。
ReleaseNotes PackageReleaseNotes empty 套件的版本資訊。
Repository/Url RepositoryUrl empty 用來複製或擷取原始程式碼的存放庫 URL。 範例: https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git
Repository/Type RepositoryType empty 存放庫類型。 範例: git (預設值), tfs
Repository/Branch RepositoryBranch empty 選擇性存放庫分支資訊。 RepositoryUrl 也必須指定這個屬性才能包含。 範例: master (NuGet 4.7.0+)。
Repository/Commit RepositoryCommit empty 選擇性的存放庫認可或變更集,表示要針對哪個來源建置套件。 RepositoryUrl 也必須指定這個屬性才能包含。 範例: 0e4d1b598f350b3dc675018d539114d1328189ef (NuGet 4.7.0+)。
PackageType <PackageType>CustomType1, 1.0.0.0;CustomType2</PackageType> 指出套件的預期用途。 封裝類型使用與套件識別碼相同的格式,並以 分隔 ;。 封裝類型可以藉由附加 ,Version 字串來建立版本。 請參閱 設定 NuGet 套件類型 (NuGet 3.5.0+)。
Summary 不支援

封裝目標輸入

屬性 說明
IsPackable 布林值,指定是否可封裝專案。 預設值是 true
SuppressDependenciesWhenPacking 設定為 , true 以隱藏所 NuGet 產生封裝的套件相依性。
PackageVersion 指定所產生之套件的版本。 接受所有形式的 NuGet 版本字串。 預設為 $(Version) 的值,也就是專案中的屬性 Version
PackageId 指定所產生之套件的名稱。 如果未指定,pack 作業會預設為使用 AssemblyName 或目錄名稱作為套件的名稱。
PackageDescription UI 顯示中的套件詳細描述。
Authors 以分號分隔的套件作者清單,符合 .org 上的nuget配置檔名稱。這些會顯示在 .org 上的NuGetnuget資源庫中,並用來由相同的作者交叉參考套件。
Description 組件的完整描述。 如果未 PackageDescription 指定,則這個屬性也會當做封裝的描述使用。
Copyright 套件的著作權詳細資料。
PackageRequireLicenseAcceptance 布林值,指定在安裝套件時,用戶端是否必須提示取用者接受套件授權。 預設值為 false
DevelopmentDependency 布爾值,指定封裝是否標示為僅限開發相依性,這可防止封裝在其他套件中包含為相依性。 使用 PackageReference (NuGet 4.8+),此旗標也表示編譯時間資產會排除在編譯之外。 如需詳細資訊,請參閱 PackageReference 的 DevelopmentDependency 支援 \(英文\)。
PackageLicenseExpression SPDX 授權識別碼或表示式,例如 Apache-2.0。 如需詳細資訊,請參閱 封裝授權表達式或許可證檔
PackageLicenseFile 如果您使用自定義授權或尚未指派 SPDX 識別碼的授權,則套件內授權檔案的路徑。
PackageLicenseUrl PackageLicenseUrl 已被取代。 請改用 PackageLicenseExpressionPackageLicenseFile
PackageProjectUrl
PackageIcon 指定套件圖示路徑,相對於封裝的根目錄。 如需詳細資訊,請參閱 封裝圖示圖像檔
PackageReleaseNotes 套件的版本資訊。
PackageReadmeFile 封裝的自述檔。
PackageTags 以分號分隔的標記清單,用以指定套件。
PackageOutputPath 決定要置放所封裝之套件的輸出路徑。 預設值為 $(OutputPath)
IncludeSymbols 此布林值會指出在封裝專案時,套件是否應該建立額外的符號套件。 符號套件的格式由 SymbolPackageFormat 屬性控制。 如需詳細資訊,請參閱 IncludeSymbols
IncludeSource 此布林值會指出封裝處理序是否應該建立來源套件。 來源套件包含程式庫的原始程式碼及 PDB 檔案。 原始程式檔會放在所產生之套件檔案中的 src/ProjectName 目錄底下。 如需詳細資訊,請參閱 IncludeSource
PackageType
IsTool 指定是否要將所有輸出檔複製到 tools 資料夾,而不是 lib 資料夾。 如需詳細資訊,請參閱 IsTool
RepositoryUrl 用來複製或擷取原始程式碼的存放庫 URL。 範例: https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git
RepositoryType 存放庫類型。 範例: git (預設值), tfs
RepositoryBranch 選擇性存放庫分支資訊。 RepositoryUrl 也必須指定這個屬性才能包含。 範例: master (NuGet 4.7.0+)。
RepositoryCommit 選擇性的存放庫認可或變更集,表示要針對哪個來源建置套件。 RepositoryUrl 也必須指定這個屬性才能包含。 範例: 0e4d1b598f350b3dc675018d539114d1328189ef (NuGet 4.7.0+)。
SymbolPackageFormat 指定符號套件的格式。 如果為 「symbols.nupkg」,則會使用 包含 PDB、DLL 和其他輸出檔案的 .symbols.nupkg 擴展名來建立舊版符號套件。 如果為 「snupkg」,則會建立包含可攜式 PDB 的 snupkg 符號套件。 默認值為 「symbols.nupkg」。。
NoPackageAnalysis 指定 pack 在建置封裝之後,不應執行封裝分析。
MinClientVersion 指定可安裝此套件的NuGet用戶端最低版本,.exenuget和 Visual Studio 封裝管理員 強制執行。
IncludeBuildOutput 這個布爾值會指定組建輸出元件是否應該封裝到 .nupkg 檔案中。
IncludeContentInPack 這個布爾值會指定是否將具有 型 Content 別的任何項目自動包含在產生的封裝中。 預設值為 true
BuildOutputTargetFolder 指定要放置輸出組件的資料夾。 輸出組件 (及其他輸出檔) 會複製到其相關的架構資料夾中。 如需詳細資訊,請參閱 輸出元件
ContentTargetFolders 指定如果未為其指定所有內容檔案 PackagePath 的預設位置。 預設值為 "content;contentFiles"。 如需詳細資訊,請參閱 Including content in a package (在套件中包含內容)。
NuspecFile 用於封裝之檔案的 .nuspec 相對或絕對路徑。 如果指定,則會專門用於封裝資訊,而且不會使用專案中的任何資訊。 如需詳細資訊,請參閱 使用 .nuspec封裝。
NuspecBasePath 檔案的 .nuspec 基底路徑。 如需詳細資訊,請參閱 使用 .nuspec封裝。
NuspecProperties 以分號分隔的索引鍵=值組清單。 如需詳細資訊,請參閱 使用 .nuspec封裝。

封裝案例

隱藏相依性

若要隱藏所 NuGet 產生套件的套件相依性,請將 設定 SuppressDependenciesWhenPackingtrue ,以允許略過產生的 nupkg 檔案中的所有相依性。

PackageIconUrl

PackageIconUrl 已被取代,有利於 PackageIcon 屬性。 從 NuGet 5.3 和 Visual Studio 2019 16.3 版開始,如果套件元數據只指定 PackageIconUrlpack就會引發 NU5048 警告。

PackageIcon

提示

若要維持與尚未支援 PackageIcon之用戶端和來源的回溯相容性,請同時指定 PackageIconPackageIconUrl。 Visual Studio 支援 PackageIcon 來自資料夾型來源的套件。

封裝圖示圖像檔

封裝圖示圖像檔案時,請使用 PackageIcon 屬性來指定圖示檔案路徑,相對於封裝的根目錄。 此外,請確定檔案包含在套件中。 圖像檔案大小限制為 1 MB。 支援的檔案格式包括 JPEG 和 PNG。 我們建議影像解析度為128x128。

例如:

<PropertyGroup>
    ...
    <PackageIcon>icon.png</PackageIcon>
    ...
</PropertyGroup>

<ItemGroup>
    ...
    <None Include="images\icon.png" Pack="true" PackagePath="\"/>
    ...
</ItemGroup>

套件圖示範例

針對對等專案 nuspec ,請查看 nuspec 圖示的參考。

PackageReadmeFile

NuGet支援 5.10.0 Preview 2.NET / SDK 5.0.300 和更新版本

封裝自述檔時,您必須使用 PackageReadmeFile 屬性來指定套件路徑,相對於封裝的根目錄。 除此之外,您必須確定檔案已包含在套件中。 支援的檔案格式只包含 Markdown (.md)。

例如:

<PropertyGroup>
    ...
    <PackageReadmeFile>readme.md</PackageReadmeFile>
    ...
</PropertyGroup>

<ItemGroup>
    ...
    <None Include="docs\readme.md" Pack="true" PackagePath="\"/>
    ...
</ItemGroup>

針對對等專案 nuspec ,請查看 nuspec 自述文件參考。

輸出組件

nuget pack 會複製副檔名為 .exe.dll.xml.winmd.json.pri 的輸出檔案。 複製的輸出檔案取決於目標所提供的BuiltOutputProjectGroup內容MSBuild。

您可以在項目檔或命令列中使用兩 MSBuild 個屬性來控制輸出元件的位置:

  • IncludeBuildOutput:布林值,決定是否應該在套件中包含組建輸出組件。
  • BuildOutputTargetFolder:指定應該在其中放置輸出組件的資料夾。 輸出組件 (及其他輸出檔) 會複製到其相關的架構資料夾中。

套件參考

請參閱專案檔中的套件參考

專案對專案參考

專案對專案參考預設 NuGet 會視為套件參考。 例如:

<ProjectReference Include="..\UwpLibrary2\UwpLibrary2.csproj"/>

您也可以將下列中繼資料新增至您的專案參考:

<IncludeAssets>
<ExcludeAssets>
<PrivateAssets>

在套件內包含內容

若要包含內容,請將額外的中繼資料新增至現有的 <Content> 項目。 除非您覆寫為下列這類項目,否則 "Content" 類型的所有項目預設都會包含在套件中:

<Content Include="..\win7-x64\libuv.txt">
 <Pack>false</Pack>
</Content>

除非您指定套件路徑,否則所有項目預設都會新增至套件內的 contentcontentFiles\any\<target_framework> 資料夾根目錄,並保留相對資料夾結構:

<Content Include="..\win7-x64\libuv.txt">
  <Pack>true</Pack>
  <PackagePath>content\myfiles\</PackagePath>
</Content>

如果您想要只將所有內容複製到特定的根資料夾(而不是 contentcontentFiles 兩者),您可以使用 MSBuild 屬性 ContentTargetFolders,其預設為「內容」;contentFiles“ 但可以設定為任何其他資料夾名稱。 請注意,根據 buildAction,只在 ContentTargetFolders 中指定 "contentFiles" 會將檔案放在 contentFiles\any\<target_framework>contentFiles\<language>\<target_framework> 下方。

PackagePath 可以是以分號分隔的一組目標路徑。 指定空的套件路徑會將檔案新增至套件的根目錄。 例如,下列會將 libuv.txt 新增至 content\myfilescontent\samples 和套件根目錄:

<Content Include="..\win7-x64\libuv.txt">
  <Pack>true</Pack>
  <PackagePath>content\myfiles;content\sample;;</PackagePath>
</Content>

也有屬性 MSBuild $(IncludeContentInPack),預設為 true。 如果這會在任何項目上設定為 false ,則來自該專案的內容不會包含在封裝中 nuget 。

您可以在上述任何項目上設定的其他套件特定元數據包括 <PackageCopyToOutput> ,以及<PackageFlatten>輸出 nuspec中專案上的contentFiles設定CopyToOutputFlatten值。

注意

除了 Content 項目之外,還可以在建置動作為 Compile、EmbeddedResource、ApplicationDefinition、Page、Resource、SplashScreen、DesignData、DesignDataWithDesignTimeCreateableTypes、CodeAnalysisDictionary、AndroidAsset、AndroidResource、BundleResource 或 None 的檔案上設定 <Pack><PackagePath> 中繼資料。

針對封裝,若要在使用萬用字元模式時將檔案名稱附加至套件路徑,您套件路徑的結尾必須是資料夾分隔符號字元,否則會將套件路徑視為包含檔案名稱的完整路徑。

IncludeSymbols

使用 MSBuild -t:pack -p:IncludeSymbols=true 時,會複製對應的 .pdb 檔案與其他輸出檔案 (.dll.exe.winmd.xml.json.pri)。 請注意,設定 IncludeSymbols=true 時會建立一般套件「和」符號套件。

IncludeSource

這與 IncludeSymbols 相同,差異在於它也會複製原始程式檔和 .pdb 檔案。 所有 Compile 類型的檔案都會覆寫 src\<ProjectName>\,並保留所產生套件中的相對路徑資料夾結構。 這也適用於任何 ProjectReference 的原始程式檔,而這些原始程式檔將 TreatAsPackageReference 設定為 false

若類型為 Compile 的檔案位於專案資料夾之外,就只會將其新增至 src\<ProjectName>\

封裝授權表達式或授權檔

使用授權表達式時,請使用 PackageLicenseExpression 屬性。 如需範例,請參閱 授權表達式範例

<PropertyGroup>
    <PackageLicenseExpression>MIT</PackageLicenseExpression>
</PropertyGroup>

若要深入瞭解 .org 所接受 NuGet的授權表達式和授權,請參閱 授權元數據

封裝授權檔案時,請使用 PackageLicenseFile 屬性來指定套件路徑,相對於套件的根目錄。 此外,請確定檔案包含在套件中。 例如:

<PropertyGroup>
    <PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
</PropertyGroup>

<ItemGroup>
    <None Include="licenses\LICENSE.txt" Pack="true" PackagePath=""/>
</ItemGroup>

如需範例,請參閱 授權檔案範例

注意

一次只能指定、 和 PackageLicenseUrlPackageLicenseExpressionPackageLicenseFile其中一個。

封裝沒有擴展名的檔案

在某些情況下,例如封裝授權檔時,您可能會想要包含沒有擴展名的檔案。 基於歷史原因, NuGet 請將 MSBuild 沒有延伸模組的路徑視為目錄。

  <PropertyGroup>
    <TargetFrameworks>netstandard2.0</TargetFrameworks>
    <PackageLicenseFile>LICENSE</PackageLicenseFile>
  </PropertyGroup>

  <ItemGroup>
    <None Include="LICENSE" Pack="true" PackagePath=""/>
  </ItemGroup>  

沒有延伸模組範例的檔案。

IsTool

使用 MSBuild -t:pack -p:IsTool=true 時,會將輸出組件案例中所指定的所有輸出檔案都複製至 tools 資料夾,而非 lib 資料夾。 請注意,這與 DotNetCliTool 不同,該項目是在 .csproj 檔案中設定 PackageType 所指定。

使用檔案封裝.nuspec

雖然建議您改為將通常.nuspec包含在專案檔中檔案中的所有屬性,但您可以選擇使用.nuspec檔案來封裝專案。 對於使用 PackageReference的非 SDK 樣式專案,您必須匯 NuGet.Build.Tasks.Pack.targets 入 ,才能執行套件工作。 您仍然需要還原專案,才能封裝 nuspec 檔案。 (SDK 樣式項目預設包含套件目標。

項目檔的目標架構無關緊要,在封裝 nuspec時不會使用。 下列三 MSBuild 個 .nuspec屬性與使用 封裝有關:

  1. NuspecFile:將用於封裝之 .nuspec 檔案的相對或絕對路徑。
  2. NuspecProperties:以分號分隔的索引鍵=值組清單。 由於命令行剖析的運作方式 MSBuild ,必須指定多個屬性,如下所示: -p:NuspecProperties="key1=value1;key2=value2"
  3. NuspecBasePath.nuspec 檔案的基底路徑。

如果使用 dotnet.exe 來封裝您的專案,則請使用下列這類命令:

dotnet pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path> 

如果使用 MSBuild 來封裝您的專案,則請使用下列這類命令:

msbuild -t:pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path> 

請注意,使用 dotnet.exe 封裝 nuspec ,或 msbuild 也會導致預設建置專案。 您可以藉由將 --no-build 屬性傳遞至 dotnet.exe,這相當於專案檔中的設定 <NoBuild>true</NoBuild> ,以及專案檔中的設定 <IncludeBuildOutput>false</IncludeBuildOutput> ,來避免這種情況。

封裝檔案的 .csproj 檔案nuspec範例如下:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <NoBuild>true</NoBuild>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <NuspecFile>PATH_TO_NUSPEC_FILE</NuspecFile>
    <NuspecProperties>add nuspec properties here</NuspecProperties>
    <NuspecBasePath>optional to provide</NuspecBasePath>
  </PropertyGroup>
</Project>

用於建立自訂套件的進階擴充點

目標 pack 提供兩個延伸點,可在內部目標架構特定組建中執行。 擴充點支援將目標架構特定內容和元件納入套件:

  • TargetsForTfmSpecificBuildOutput 目標:用於資料夾內的 lib 檔案,或使用 指定的 BuildOutputTargetFolder資料夾。
  • TargetsForTfmSpecificContentInPackage 目標:用於外部的 BuildOutputTargetFolder檔案。

TargetsForTfmSpecificBuildOutput

撰寫自定義目標,並將它指定為 屬性的值 $(TargetsForTfmSpecificBuildOutput) 。 針對任何需要進入 BuildOutputTargetFolder 的檔案 (預設為 lib),目標應該將這些檔案寫入 ItemGroup BuildOutputInPackage ,並設定下列兩個元數據值:

  • FinalOutputPath:檔案的絕對路徑;如果未提供,則會使用身分識別來評估來源路徑。
  • TargetPath:(選擇性) 設定檔案何時需要進入 內的 lib\<TargetFramework> 子資料夾,例如位於其個別文化資料夾下的附屬元件。 預設為檔名。

範例:

<PropertyGroup>
  <TargetsForTfmSpecificBuildOutput>$(TargetsForTfmSpecificBuildOutput);GetMyPackageFiles</TargetsForTfmSpecificBuildOutput>
</PropertyGroup>

<Target Name="GetMyPackageFiles">
  <ItemGroup>
    <BuildOutputInPackage Include="$(OutputPath)cs\$(AssemblyName).resources.dll">
        <TargetPath>cs</TargetPath>
    </BuildOutputInPackage>
  </ItemGroup>
</Target>

TargetsForTfmSpecificContentInPackage

撰寫自定義目標,並將它指定為 屬性的值 $(TargetsForTfmSpecificContentInPackage) 。 針對要包含在封裝中的任何檔案,目標應該將這些檔案寫入 ItemGroup TfmSpecificPackageFile ,並設定下列選擇性元數據:

  • PackagePath:檔案應在封裝中輸出的路徑。 NuGet 如果將多個檔案新增至相同的套件路徑,就會發出警告。
  • BuildAction:要指派給檔案的建置動作,只有在封裝路徑位於 contentFiles 資料夾中時才需要。 預設為 「None」。。

範例:

<PropertyGroup>
  <TargetsForTfmSpecificContentInPackage>$(TargetsForTfmSpecificContentInPackage);CustomContentTarget</TargetsForTfmSpecificContentInPackage>
</PropertyGroup>

<Target Name="CustomContentTarget">
  <ItemGroup>
    <TfmSpecificPackageFile Include="abc.txt">
      <PackagePath>mycontent/$(TargetFramework)</PackagePath>
    </TfmSpecificPackageFile>
    <TfmSpecificPackageFile Include="Extensions/ext.txt" Condition="'$(TargetFramework)' == 'net46'">
      <PackagePath>net46content</PackagePath>
    </TfmSpecificPackageFile>  
  </ItemGroup>
</Target>  

還原目標

MSBuild -t:restore (nuget restoredotnet restore 與 .NET Core 專案搭配使用) 會還原專案檔中所參考的套件,如下所示:

  1. 讀取所有專案對專案參考
  2. 讀取專案屬性來尋找中繼資料夾和目標架構
  3. 將資料傳遞 MSBuild 至 NuGet。Build.Tasks.dll
  4. 執行還原
  5. 下載套件
  6. 撰寫資產檔案、目標和屬性

目標 restore 適用於使用 PackageReference 格式的專案。 MSBuild 16.5+也支援packages.config格式。

注意

目標restore不應與build目標結合執行

還原屬性

其他還原設定可能來自 MSBuild 項目檔中的屬性。 您也可以從命令列,使用 -p: 參數設定值 (請參閱下列<範例>)。

屬性 說明
RestoreSources 以分號分隔的套件來源清單。
RestorePackagesPath 使用者套件資料夾路徑。
RestoreDisableParallel 限制逐一進行下載。
RestoreConfigFile 要套用之 Nuget.Config 檔案的路徑。
RestoreNoHttpCache 如果為 true,請避免使用 HTTP 快取套件。 請參閱 管理全域套件和快取資料夾
RestoreIgnoreFailedSources 如果為 true,請忽略失敗或遺漏的套件來源。
RestoreFallbackFolders 後援資料夾,與使用者套件資料夾使用的方式相同。
RestoreAdditionalProjectSources 還原期間要使用的其他來源。
RestoreAdditionalProjectFallbackFolders 還原期間要使用的其他後援資料夾。
RestoreAdditionalProjectFallbackFoldersExcludes 排除 中指定的後援資料夾 RestoreAdditionalProjectFallbackFolders
RestoreTaskAssemblyFile NuGet.Build.Tasks.dll 的路徑。
RestoreGraphProjectInput 要還原的專案清單 (以分號分隔),其中應包含絕對路徑。
RestoreUseSkipNonexistentTargets 透過收集 MSBuild 專案時,會決定是否使用 SkipNonexistentTargets 優化收集這些專案。 未設定時,預設為 true。 當無法匯入項目的目標時,後果是失敗的行為。
MSBuildProjectExtensionsPath 輸出資料夾,預設為 BaseIntermediateOutputPathobj 資料夾。
RestoreForce 在 PackageReference 型專案中,強制解析所有相依性,即使上次還原成功也一樣。 指定此旗標類似於刪除 project.assets.json 檔案。 這不會略過 HTTP-cache。
RestorePackagesWithLockFile 選擇使用鎖定檔案。
RestoreLockedMode 以鎖定模式執行還原。 這表示還原不會重新評估相依性。
NuGetLockFilePath 鎖定檔案的自定義位置。 預設位置位於項目旁邊,並命名為 packages.lock.json
RestoreForceEvaluate 強制還原以重新計算相依性,並更新鎖定檔案,而不會有任何警告。
RestorePackagesConfig 選擇加入參數,可還原具有 packages.config 的專案。只支援 MSBuild -t:restore
RestoreRepositoryPath 僅限 packages.config。 指定要還原封裝的套件目錄。 SolutionDirectory 如果未指定,將會使用 。
RestoreUseStaticGraphEvaluation 選擇加入參數,以使用靜態圖形 MSBuild 評估,而不是標準評估。 靜態圖表評估是大型存放庫和解決方案的實驗性功能。
RestoreUseLegacyDependencyResolver 退出退出以使用舊版相依性解析程式。 NuGet的相依性解析程序實作已在 6.12 版本中重寫。 這個參數會強制使用先前的演算法。

屬性 ExcludeRestorePackageImports 是所使用的 NuGet內部屬性。 它不應該在任何檔案中 MSBuild 修改或設定。

範例

命令列:

msbuild -t:restore -p:RestoreConfigFile=<path>

專案檔:

<PropertyGroup>
    <RestoreIgnoreFailedSources>true</RestoreIgnoreFailedSources>
</PropertyGroup>

Restore outputs

還原會在組建 obj 資料夾中建立下列檔案:

檔案 說明
project.assets.json 包含所有套件參考的相依性圖形。
{projectName}.projectFileExtension.nuget.g.props MSBuild套件中包含的屬性參考
{projectName}.projectFileExtension.nuget.g.targets MSBuild套件中包含的目標參考

使用一個 MSBuild 命令還原和建置

NuGet由於可以還原關閉MSBuild目標和屬性的套件,還原和建置評估會使用不同的全域屬性執行。 這表示下列專案會有無法預測且通常不正確的行為。

msbuild -t:restore,build

相反地,建議的方法是:

msbuild -t:build -restore

相同的邏輯會套用至類似 build的其他目標。

使用 還原 PackageReference 和 packages.config 專案 MSBuild

使用 MSBuild 16.5+ 時,也支援 packages.config。msbuild -t:restore

msbuild -t:restore -p:RestorePackagesConfig=true

注意

packages.config 還原僅適用於 MSBuild 16.5+,而非使用 dotnet.exe

使用 MSBuild 靜態圖形評估還原

注意

使用 MSBuild 16.6+ 時, NuGet 已新增實驗性功能,以從命令行使用靜態圖形評估,大幅改善大型存放庫的還原時間。

msbuild -t:restore -p:RestoreUseStaticGraphEvaluation=true

或者,您可以在 Directory.Build.Props 中設定 屬性來啟用它。

<Project>
  <PropertyGroup>
    <RestoreUseStaticGraphEvaluation>true</RestoreUseStaticGraphEvaluation>
  </PropertyGroup>
</Project>

注意

自 Visual Studio 2019.x 和 NuGet 5.x 起,這項功能會被視為實驗性且加入宣告。 請遵循 NuGet/Home#9803 以取得此功能默認啟用時的詳細數據。

靜態圖形還原會 msbuild 變更還原的部分、專案讀取和評估,但不會變更還原演算法! 還原演算法在所有 NuGet 工具中都相同(NuGet.exe、 MSBuild.exe、dotnet.exe和 Visual Studio)。

在極少數的情況下,靜態圖形還原的行為可能會與目前的還原不同,而且某些宣告的 PackageReferences 或 ProjectReferences 可能遺失。

若要簡化您的心意,在移轉至靜態圖形還原時,請考慮執行:

msbuild.exe -t:restore -p:RestoreUseStaticGraphEvaluation=true
msbuild.exe -t:restore

NuGet不應報告任何變更。 如果您看到差異,請在 /Home 提出問題。NuGet

取代還原圖形中的一個程式庫

如果還原內含錯誤的組件,您可以排除該套件預設選項,並將其取代為您自己的選項。 首先,會有最上層 PackageReference,但排除所有資產:

<PackageReference Include="Newtonsoft.Json" Version="9.0.1">
  <ExcludeAssets>All</ExcludeAssets>
</PackageReference>

接下來,新增您自己對 DLL 之適當本機複本的參考:

<Reference Include="Newtonsoft.Json.dll" />