project.json 參考

2025-02-05

重要

此內容已被取代。項目應該使用 PackageReference 格式。瞭解如何將 project.json 項目移轉至 PackageReference。

NuGet 3.x

project.json 檔案會維護專案中所使用的套件清單，稱為套件管理格式。它會取代 packages.config，但接著會由 nuGet 4.0+ PackageReference 取代。

project.lock.json 檔案（如下所述）也用於採用 project.json的專案。

project.json 具有下列基本結構，其中四個最上層物件的每一個都可以有任意數目的子物件：

{
    "dependencies": {
        "PackageID" : "{version_constraint}"
    },
    "frameworks" : {
        "TxM" : {}
    },
    "runtimes" : {
        "RID": {}
    },
    "supports" : {
        "CompatibilityProfile" : {}
    }
}

將 project.json 移轉至 PackageReference

project.json 與 PackageReference 之間的移轉很簡單。最簡單的方式是使用最新 Visual Studio 2022 Update 14 中的內建移轉程式。

在 Visual Studio 中載入 project.json 專案。
移至 project.json 專案的方案總管，並尋找相依性節點。
按兩下 [Migrate project.json to PackageReference...！

從 project.json 移轉至 PackageReference

或者，您可以使用 dotnet migrate，或藉由從 project.json 檔案取得所有內容，並以對等 PackageReference 語法取代它，手動進行移轉。

依賴

以下列形式列出專案的 NuGet 套件相依性：

"PackageID" : "version_constraint"

例如：

"dependencies": {
    "Microsoft.NETCore": "5.0.0",
    "System.Runtime.Serialization.Primitives": "4.0.10"
}

[dependencies] 區段是 [NuGet 套件管理員] 對話框將套件相依性新增至專案的位置。

套件識別碼會對應至 nuget.org 上的套件識別碼，與套件管理員控制台中使用的識別子相同：Install-Package Microsoft.NETCore。

還原套件時，"5.0.0" 的版本條件約束表示 >= 5.0.0。也就是說，如果伺服器上無法使用5.0.0，但5.0.1是，NuGet會安裝5.0.1，並警告您升級。否則，NuGet 會挑選符合條件約束之伺服器上的最低可能版本。

如需解決規則的詳細資訊，請參閱相依性解析。

管理相依性資產

相依性中的哪些資產會流向最上層專案，方法是在相依性參考的 include 和 exclude 屬性中指定逗號分隔的標記集。這些標籤會列在下表中：

Include/Exclude 標籤	目標受影響的資料夾
contentFiles	內容
運行	運行時間、資源和 FrameworkAssemblies
編譯	自由
建	build （MSBuild props and targets）
本地	本地
沒有	沒有資料夾
都	所有資料夾

以 exclude 指定的標記優先於使用 include所指定的標記。例如，include="runtime, compile" exclude="compile" 與 include="runtime"相同。

例如，若要包含相依性 build 和 native 資料夾，請使用下列專案：

{
  "dependencies": {
    "packageA": {
      "version": "1.0.0",
      "include": "build, native"
    }
  }
}

若要排除相依性 content 和 build 資料夾，請使用下列專案：

{
  "dependencies": {
    "packageA": {
      "version": "1.0.0",
      "exclude": "contentFiles, build"
    }
  }
}

框架

列出項目執行的架構，例如 net45、netcoreapp、netstandard。

"frameworks": {
    "netcore50": {}
    }

frameworks 區段中只允許單一專案。（例外狀況是針對使用已取代 DNX 工具鏈建置的 ASP.NET 專案 project.json 檔案，允許多個目標。

運行時間

列出應用程式執行的作系統和架構，例如 win10-arm、win8-x64、win8-x86。

"runtimes": {
    "win10-arm": { },
    "win10-arm-aot": { },
    "win10-x86": { },
    "win10-x86-aot": { },
    "win10-x64": { },
    "win10-x64-aot": { }
}

包含可在任何運行時間上執行之 PCL 的套件不需要指定運行時間。這也必須是任何相依性，否則您必須指定運行時間。

支援

定義套件相依性的一組檢查。您可以定義預期 PCL 或應用程式執行的位置。定義沒有限制，因為您的程式代碼可能會在其他地方執行。但指定這些檢查可讓 NuGet 檢查列出的 TxM 上滿足所有相依性。值的範例包括：net46.app、uwp.10.0.app等。

當您選取 [可攜式類別庫目標] 對話框中的專案時，應該會自動填入本節。

"supports": {
    "net46.app": {},
    "uwp.10.0.app": {}
}

進口

匯入的設計目的是允許使用 dotnet TxM 的套件，以未宣告 dotnet TxM 的套件運作。如果您的專案使用 dotnet TxM，則您相依的所有套件也必須有 dotnet TxM，除非您將下列內容新增至您的 project.json，以允許非 dotnet 平臺與 dotnet相容：

"frameworks": {
    "dotnet": { "imports" : "portable-net45+win81" }
}

如果您使用 dotnet TxM，PCL 專案系統會根據支援的目標新增適當的 imports 語句。

與可攜式應用程式和 Web 項目的差異

NuGet 所使用的 project.json 檔案是 ASP.NET Core 專案中找到的子集。在 ASP.NET Core project.json 會用於專案元數據、編譯資訊和相依性。在其他項目系統中使用時，這三件事會分割成個別的檔案，project.json 包含較少的資訊。值得注意的差異包括：

frameworks 區段中只能有一個架構。
檔案不能包含您在 DNX project.json 檔案中看到的相依性、編譯選項等。假設只能有單一架構，輸入架構特定的相依性並無意義。
編譯是由 MSBuild 處理，因此編譯選項、預處理器定義等都是 MSBuild 專案檔的一部分，而不是 project.json。

在 NuGet 3+ 中，開發人員不會手動編輯 project.json，因為 Visual Studio 中的套件管理員 UI 會作內容。也就是說，您當然可以編輯檔案，但您必須建置專案，才能以另一種方式啟動套件還原或叫用還原。請參閱套件還原。

project.lock.json

project.lock.json 檔案會在使用 project.json的專案還原 NuGet 套件的過程中產生。它會保存 NuGet 所產生之所有資訊的快照集，其會逐步解說套件的圖形，並包含您專案中所有套件的版本、內容和相依性。建置系統會使用此方式，從建置專案時相關的全域位置選擇套件，而不是根據專案本身的本機 packages 資料夾而定。這會導致更快速的建置效能，因為必須只讀取 project.lock.json，而不是許多個別的 .nuspec 檔案。

套件還原時會自動產生 project.lock.json，因此可以透過將它新增至 .gitignore 和 .tfignore 檔案，從原始檔控制中省略它（請參閱套件和原始檔控制。不過，如果您將其包含在原始檔控制中，變更歷程記錄會顯示隨著時間解析的相依性變更。

共用方式為