=========================================================================================

微軟官方建立NuGet包說明文件

具體的可以參考：https://docs.microsoft.com/zh-cn/nuget/create-packages/overview-and-workflow

=========================================================================================

從零開始製作 NuGet 原始碼包（全面支援 .NET Core / .NET Framework / WPF 專案）

2019-06-16 12:53

預設情況下，我們打包 NuGet 包時，目標專案安裝我們的 NuGet 包會引用我們生成的庫檔案（dll）。除此之外，我們也可以專門做 NuGet 工具包，還可以做 NuGet 原始碼包。然而做原始碼包可能是其中最困難的一種了，目標專案安裝完後，這些原始碼將直接隨目標專案一起編譯。

本文將從零開始，教你製作一個支援 .NET 各種型別專案的原始碼包。

本文內容

• 前置知識
• 製作一個原始碼包
  • 第一步：建立一個 .NET 專案
  • 第二步：組織專案的目錄結構
  • 第三步：編寫專案檔案 csproj
  • 第四步：編寫編譯檔案 targets
    • buildMultiTargeting 資料夾中的 Package.props 檔案
    • buildMultiTargeting 資料夾中的 Package.targets 檔案
    • build 資料夾中的 Package.props 檔案
    • build 資料夾中的 Package.targets 檔案
    • 這四個檔案分別的作用
    • 體驗和檢視 NuGet 原始碼包
  • 第五步：加入 WPF 專案支援
    • build 資料夾中的 Package.props 檔案
    • build 資料夾中的 Package.targets 檔案
  • 測試和釋出原始碼包
• 完整專案結構和原始碼
  • 目錄結構
  • 專案檔案
  • 編譯檔案
  • 開源專案
• 更多內容
  • SourceYard 開源專案
  • 相關部落格

前置知識

在開始製作一個原始碼包之間，建議你提前瞭解專案檔案的一些基本概念：

• 理解 C# 專案 csproj 檔案格式的本質和編譯流程

當然就算不了解也沒有關係。跟著本教程你也可以製作出來一個原始碼包，只不過可能遇到了問題的時候不容易除錯和解決。

製作一個原始碼包

接下來，我們將從零開始製作一個原始碼包。

我們接下來的將建立一個完整的解決方案，這個解決方案包括：

1. 一個將打包成原始碼包的專案
2. 一個除錯專用的專案（可選）
3. 一個測試原始碼包的專案（可選）

第一步：建立一個 .NET 專案

像其他 NuGet 包的引用專案一樣，我們需要建立一個空的專案。不過差別是我們需要建立的是控制檯程式。

當建立好之後，Main 函式中的所有內容都是不需要的，於是我們刪除 Main 函式中的所有內容但保留 Main 函式。

這時 Program.cs 中的內容如下：

namespace Walterlv.PackageDemo.SourceCode
{
    class Program
    {
        static void Main(string[] args)
        {
        }
    }
}

雙擊建立好的專案的專案，或者右鍵專案 “編輯專案檔案”，我們可以編輯此專案的 csproj 檔案。

在這裡，我將目標框架改成了 net48。實際上如果我們不製作動態原始碼生成，那麼這裡無論填寫什麼目標框架都不重要。在這篇部落格中，我們主要篇幅都會是做靜態原始碼生成，所以你大可不必關心這裡填什麼。

提示：如果 net48 讓你無法編譯這個專案，說明你電腦上沒有裝 .NET Framework 4.8 框架，請改成 net473,net472,net471,net47,net462,net 461,net46,net45,netcoreapp3.0,netcoreapp2.1,netcoreapp2.0 中的任何一個可以讓你編譯通過的目標框架即可。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net48</TargetFramework>
  </PropertyGroup>

</Project>

第二步：組織專案的目錄結構

接下來，我們會讓這個專案像一個 NuGet 包的樣子。當然，是 NuGet 原始碼包。

請在你的專案當中建立這些檔案和資料夾：

- Assets
    - build
        + Package.props
        + Package.targets
    - buildMultiTargeting
        + Package.props
        + Package.targets
    - src
        + Foo.cs
    - tools
+ Program.cs

在這裡，- 號表示資料夾，+ 號表示檔案。

Program.cs 是我們一開始就已經有的，可以不用管。src 資料夾裡的 Foo.cs 是我隨意建立的一個類，你就想往常建立正常的類檔案一樣建立一些類就好了。

比如我的 Foo.cs 裡面的內容很簡單：

using System;

namespace Walterlv.PackageDemo.SourceCode
{
    internal class Foo
    {
        public static void Print() => Console.WriteLine("Walterlv is a 逗比.");
    }
}

props 和 targets 檔案你可能在 Visual Studio 的新建檔案的模板中找不到這樣的模板檔案。這不重要，你隨便建立一個文字檔案，然後將名稱修改成上面列舉的那樣即可。接下來我們會依次修改這些檔案中的所有內容，所以無需擔心模板自動為我們生成了哪些內容。

為了更直觀，我將我的解決方案截圖貼出來，裡面包含所有這些檔案和資料夾的解釋。

我特別說明了哪些檔案和資料夾是必須存在的，哪些檔案和資料夾的名稱一定必須與本文說明的一樣。如果你是以教程的方式閱讀本文，建議所有的檔案和資料夾都跟我保持一樣的結構和名稱；如果你已經對 NuGet 包的結構有一定了解，那麼可自作主張修改一些名稱。

第三步：編寫專案檔案 csproj

現在，我們要雙擊專案名稱或者右鍵“編輯專案檔案”來編輯專案的 csproj 檔案

我們編輯專案檔案的目的，是讓我們前一步建立的專案資料夾結構真正成為 NuGet 包中的資料夾結構。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net48</TargetFramework>

    <!-- 要求此專案編譯時要生成一個 NuGet 包。-->
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>

    <!-- 這裡為了方便，我將 NuGet 包的輸出路徑設定在瞭解決方案根目錄的 bin 資料夾下，而不是專案的 bin 資料夾下。-->
    <PackageOutputPath>..\bin\$(Configuration)</PackageOutputPath>

    <!-- 建立 NuGet 包時，專案的輸出檔案對應到 NuGet 包的 tools 資料夾，這可以避免目標專案引用我們的 NuGet 包的輸出檔案。
         同時，如果將來我們準備動態生成原始碼，而不只是引入靜態原始碼，還可以有機會執行我們 Program 中的 Main 函式。-->
    <BuildOutputTargetFolder>tools</BuildOutputTargetFolder>

    <!-- 此包將不會傳遞依賴。意味著如果目標專案安裝了此 NuGet 包，那麼安裝目標專案包的專案不會間接安裝此 NuGet 包。-->
    <DevelopmentDependency>true</DevelopmentDependency>
    
    <!-- 包的版本號，我們設成了一個預覽版；當然你也可以設定為正式版，即沒有後面的 -alpha 字尾。-->
    <Version>0.1.0-alpha</Version>
    
    <!-- 設定包的作者。在上傳到 nuget.org 之後，如果作者名與 nuget.org 上的賬號名相同，其他人瀏覽包是可以直接點選連結看作者頁面。-->
    <Authors>walterlv</Authors>

    <!-- 設定包的組織名稱。我當然寫成我所在的組織 dotnet 職業技術學院啦。-->
    <Company>dotnet-campus</Company>
  </PropertyGroup>

  <!-- 在生成 NuGet 包之前，我們需要將我們專案中的資料夾結構一一對映到 NuGet 包中。-->
  <Target Name="IncludeAllDependencies" BeforeTargets="_GetPackageFiles">
    <ItemGroup>

      <!-- 將 Package.props / Package.targets 檔案的名稱在 NuGet 包中改為需要的真正名稱。
           因為 NuGet 包要自動匯入 props 和 targets 檔案，要求檔案的名稱必須是 包名.props 和 包名.targets；
           然而為了避免我們改包名的時候還要同步改四個檔案的名稱，所以就在專案檔案中動態生成。-->
      <None Include="Assets\build\Package.props" Pack="True" PackagePath="build\$(PackageId).props" />
      <None Include="Assets\build\Package.targets" Pack="True" PackagePath="build\$(PackageId).targets" />
      <None Include="Assets\buildMultiTargeting\Package.props" Pack="True" PackagePath="buildMultiTargeting\$(PackageId).props" />
      <None Include="Assets\buildMultiTargeting\Package.targets" Pack="True" PackagePath="buildMultiTargeting\$(PackageId).targets" />

      <!-- 我們將 src 目錄中的所有原始碼對映到 NuGet 包中的 src 目錄中。-->
      <None Include="Assets\src\**" Pack="True" PackagePath="src" />

    </ItemGroup>
  </Target>

</Project>

第四步：編寫編譯檔案 targets

接下來，我們將編寫編譯檔案 props 和 targets。注意，我們需要寫的是四個檔案的內容，不要弄錯了。

如果我們做好的 NuGet 原始碼包被其他專案使用，那麼這四個檔案中的其中一對會在目標專案被自動匯入（Import）。在你理解 理解 C# 專案 csproj 檔案格式的本質和編譯流程 一文內容之前，你可能不明白“匯入”是什麼意思。但作為從零開始的入門部落格，你也不需要真的理解匯入是什麼意思，只要知道這四個檔案中的程式碼將在目標專案編譯期間執行就好。

buildMultiTargeting 資料夾中的 Package.props 檔案

你只需要將下面的程式碼拷貝到 buildMultiTargeting 資料夾中的 Package.props 檔案即可。注意將包名換成你自己的包名，也就是專案名。

<Project>

  <PropertyGroup>
    <MSBuildAllProjects>$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>
  </PropertyGroup>
  
  <!-- 為了簡單起見，如果匯入了這個檔案，那麼我們將直接再匯入 ..\build\Walterlv.PackageDemo.SourceCode.props 檔案。
       注意到了嗎？我們並沒有寫 Package.props，因為我們在第三步編寫專案檔案時已經將這個檔案轉換為真實的包名了。-->
  <Import Project="..\build\Walterlv.PackageDemo.SourceCode.props" />

</Project>

buildMultiTargeting 資料夾中的 Package.targets 檔案

你只需要將下面的程式碼拷貝到 buildMultiTargeting 資料夾中的 Package.targets 檔案即可。注意將包名換成你自己的包名，也就是專案名。

<Project>

  <PropertyGroup>
    <MSBuildAllProjects>$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>
  </PropertyGroup>
  
  <!-- 為了簡單起見，如果匯入了這個檔案，那麼我們將直接再匯入 ..\build\Walterlv.PackageDemo.SourceCode.targets 檔案。
       注意到了嗎？我們並沒有寫 Package.targets，因為我們在第三步編寫專案檔案時已經將這個檔案轉換為真實的包名了。-->
  <Import Project="..\build\Walterlv.PackageDemo.SourceCode.targets" />

</Project>

build 資料夾中的 Package.props 檔案

下面是 build 資料夾中 Package.props 檔案的全部內容。可以注意到我們幾乎沒有任何實質性的程式碼在裡面。即便我們在此檔案中還沒有寫任何程式碼，依然需要建立這個檔案，因為後面第五步我們將新增更復雜的程式碼時將再次用到這個檔案完成裡面的內容。

現在，保持你的檔案中的內容與下面一模一樣就好。

<Project>

  <PropertyGroup>
    <MSBuildAllProjects>$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>
  </PropertyGroup>

</Project>

build 資料夾中的 Package.targets 檔案

下面是 build 資料夾中的 Package.targets 檔案的全部內容。

我們寫了兩個編譯目標，即 Target。_WalterlvDemoEvaluateProperties 沒有指定任何執行時機，但幫我們計算了兩個屬性：

• _WalterlvDemoRoot 即 NuGet 包的根目錄
• _WalterlvDemoSourceFolder 即 NuGet 包中的原始碼目錄

另外，我們添加了一個 Message 任務，用於在編譯期間顯示一條資訊，這對於除錯來說非常方便。

_WalterlvDemoIncludeSourceFiles 這個編譯目標指定在 CoreCompile 之前執行，並且執行需要依賴於 _WalterlvDemoEvaluateProperties 編譯目標。這意味著當編譯執行到 CoreCompile 步驟時，將在它執行之前插入 _WalterlvDemoIncludeSourceFiles 編譯目標來執行，而 _WalterlvDemoIncludeSourceFiles 依賴於 _WalterlvDemoEvaluateProperties，於是 _WalterlvDemoEvaluateProperties 會插入到更之前執行。那麼在微觀上來看，這三個編譯任務的執行順序將是：_WalterlvDemoEvaluateProperties -> _WalterlvDemoIncludeSourceFiles -> CoreCompile。

_WalterlvDemoIncludeSourceFiles 中，我們定義了一個集合 _WalterlvDemoCompile，集合中包含 NuGet 包原始碼資料夾中的所有 .cs 檔案。另外，我們又定義了 Compile 集合，將 _WalterlvDemoCompile 集合中的所有內容新增到 Compile 集合中。Compile 是 .NET 專案中的一個已知集合，當 CoreCompile 執行時，所有 Compile 集合中的檔案將參與編譯。注意到我沒有直接將 NuGet 包中的原始碼檔案引入到 Compile 集合中，而是經過了中轉。後面第五步中，你將體會到這樣做的作用。

我們也新增一個 Message 任務，用於在編譯期間顯示資訊，便於除錯。

<Project>

  <PropertyGroup>
    <MSBuildAllProjects>$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>
  </PropertyGroup>

  <Target Name="_WalterlvDemoEvaluateProperties">
    <PropertyGroup>
      <_WalterlvDemoRoot>$(MSBuildThisFileDirectory)..\</_WalterlvDemoRoot>
      <_WalterlvDemoSourceFolder>$(MSBuildThisFileDirectory)..\src\</_WalterlvDemoSourceFolder>
    </PropertyGroup>
    <Message Text="1. 初始化原始碼包的編譯屬性" />
  </Target>

  <!-- 引入 C# 原始碼。 -->
  <Target Name="_WalterlvDemoIncludeSourceFiles"
          BeforeTargets="CoreCompile"
          DependsOnTargets="_WalterlvDemoEvaluateProperties">
    <ItemGroup>
      <_WalterlvDemoCompile Include="$(_WalterlvDemoSourceFolder)**\*.cs" />
      <Compile Include="@(_WalterlvDemoCompile)" />
    </ItemGroup>
    <Message Text="2 引入原始碼包中的所有原始碼：@(_WalterlvDemoCompile)" />
  </Target>

</Project>

這四個檔案分別的作用

我們剛剛花了很大的篇幅教大家完成 props 和 targets 檔案，那麼這四個檔案是做什麼的呢？

如果安裝我們原始碼包的專案使用 TargetFramework 屬性寫目標框架，那麼 NuGet 會自動幫我們匯入 build 資料夾中的兩個編譯檔案。如果安裝我們原始碼包的專案使用 TargetFrameworks（注意複數形式）屬性寫目標框架，那麼 NuGet 會自動幫我們匯入 buildMultiTargeting 資料夾中的兩個編譯檔案。

如果你對這個屬性不熟悉，請回到第一步看我們一開始建立的程式碼，你會看到這個屬性的設定的。如果還不清楚，請閱讀部落格：

• 讓一個 csproj 專案指定多個開發框架

體驗和檢視 NuGet 原始碼包

也許你已經從本文拷貝了很多程式碼過去了，但直到目前我們還沒有看到這些程式碼的任何效果，那麼現在我們就可以來看看了。這可算是一個階段性成果呢！

先編譯生成一下我們一直在完善的專案，我們就可以在解決方案目錄的 bin\Debug 目錄下找到一個 NuGet 包。

現在，我們要開啟這個 NuGet 包看看裡面的內容。你需要先去應用商店下載 NuGet Package Explorer，裝完之後你就可以開始直接雙擊 NuGet 包檔案，也就是 nupkg 檔案。現在我們雙擊開啟看看。

我們的體驗到此為止。如果你希望在真實的專案當中測試，可以閱讀其他部落格瞭解如何在本地測試 NuGet 包。

第五步：加入 WPF 專案支援

截至目前，我們只是在原始碼包中引入了 C# 程式碼。如果我們需要加入到原始碼包中的程式碼包含 WPF 的 XAML 檔案，或者安裝我們原始碼包的目標專案包含 WPF 的 XAML 檔案，那麼這個 NuGet 原始碼包直接會導致無法編譯通過。至於原因，你需要閱讀我的另一篇部落格來了解：

• WPF 程式的編譯過程

即便你不懂 WPF 程式的編譯過程，你也可以繼續完成本文的所有內容，但可能就不會明白為什麼接下來我們要那樣去修改我們之前建立的檔案。

接下來我們將修改這些檔案：

• build 資料夾中的 Package.props 檔案
• build 資料夾中的 Package.targets 檔案

build 資料夾中的 Package.props 檔案

在這個檔案中，我們將新增一個屬性 ShouldFixNuGetImportingBugForWpfProjects。這是我取的名字，意為“是否應該修復 WPF 專案中 NuGet 包自動匯入的問題”。

我做一個開關的原因是懷疑我們需要針對 WPF 專案進行特殊處理是 WPF 專案自身的 Bug，如果將來 WPF 修復了這個 Bug，那麼我們將可以直接通過此開關來關閉我們在這一節做的特殊處理。另外，後面我們將採用一些特別的手段來除錯我們的 NuGet 原始碼包，在除錯專案中我們也會將這個屬性設定為 False 以關閉 WPF 專案的特殊處理。

    <Project>
    
      <PropertyGroup>
        <MSBuildAllProjects>$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>
    
++      <!-- 當生成 WPF 臨時專案時，不會自動 Import NuGet 中的 props 和 targets 檔案，這使得在臨時專案中你現在看到的整個檔案都不會參與編譯。
++           然而，我們可以通過欺騙的方式在主專案中通過 _GeneratedCodeFiles 集合將需要編譯的檔案傳遞到臨時專案中以間接參與編譯。
++           WPF 臨時專案不會 Import NuGet 中的 props 和 targets 可能是 WPF 的 Bug，也可能是刻意如此。
++           所以我們通過一個屬性開關 `ShouldFixNuGetImportingBugForWpfProjects` 來決定是否修復這個錯誤。-->
++      <ShouldFixNuGetImportingBugForWpfProjects Condition=" ‘$(ShouldFixNuGetImportingBugForWpfProjects)‘ == ‘‘ ">True</ShouldFixNuGetImportingBugForWpfProjects>
++    </PropertyGroup>
    
    </Project>

build 資料夾中的 Package.targets 檔案

請按照下面的差異說明來修改你的 Package.targets 檔案。實際上我們幾乎刪除任何程式碼，所以其實你可以將下面的所有內容作為你的新的 Package.targets 中的內容。

    <Project>
    
      <PropertyGroup>
        <MSBuildAllProjects>$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>
      </PropertyGroup>

++    <PropertyGroup>
++      <!-- 我們增加了一個屬性，用於處理 WPF 特殊專案的原始碼之前，確保我們已經收集到所有需要引入的原始碼。 -->
++      <_WalterlvDemoImportInWpfTempProjectDependsOn>_WalterlvDemoIncludeSourceFiles</_WalterlvDemoImportInWpfTempProjectDependsOn>
++    </PropertyGroup>
    
      <Target Name="_WalterlvDemoEvaluateProperties">
        <PropertyGroup>
          <_WalterlvDemoRoot>$(MSBuildThisFileDirectory)..\</_WalterlvDemoRoot>
          <_WalterlvDemoSourceFolder>$(MSBuildThisFileDirectory)..\src\</_WalterlvDemoSourceFolder>
        </PropertyGroup>
        <Message Text="1. 初始化原始碼包的編譯屬性" />
      </Target>
    
      <!-- 引入 C# 原始碼。 -->
      <Target Name="_WalterlvDemoIncludeSourceFiles"
              BeforeTargets="CoreCompile"
              DependsOnTargets="_WalterlvDemoEvaluateProperties">
        <ItemGroup>
          <_WalterlvDemoCompile Include="$(_WalterlvDemoSourceFolder)**\*.cs" />
++        <_WalterlvDemoAllCompile Include="@(_WalterlvDemoCompile)" />
          <Compile Include="@(_WalterlvDemoCompile)" />
        </ItemGroup>
--      <Message Text="2 引入原始碼包中的所有原始碼：@(_WalterlvDemoCompile)" />
++      <Message Text="2.1 引入原始碼包中的所有原始碼：@(_WalterlvDemoCompile)" />
      </Target>
    
++    <!-- 引入 WPF 原始碼。 -->
++    <Target Name="_WalterlvDemoIncludeWpfFiles"
++            BeforeTargets="MarkupCompilePass1"
++            DependsOnTargets="_WalterlvDemoEvaluateProperties">
++      <ItemGroup>
++        <_WalterlvDemoPage Include="$(_WalterlvDemoSourceFolder)**\*.xaml" />
++        <Page Include="@(_WalterlvDemoPage)" Link="%(_WalterlvDemoPage.FileName).xaml" />
++      </ItemGroup>
++      <Message Text="2.2 引用 WPF 相關原始碼：@(_WalterlvDemoPage)" />
++    </Target>

++    <!-- 當生成 WPF 臨時專案時，不會自動 Import NuGet 中的 props 和 targets 檔案，這使得在臨時專案中你現在看到的整個檔案都不會參與編譯。
++         然而，我們可以通過欺騙的方式在主專案中通過 _GeneratedCodeFiles 集合將需要編譯的檔案傳遞到臨時專案中以間接參與編譯。
++         WPF 臨時專案不會 Import NuGet 中的 props 和 targets 可能是 WPF 的 Bug，也可能是刻意如此。
++         所以我們通過一個屬性開關 `ShouldFixNuGetImportingBugForWpfProjects` 來決定是否修復這個錯誤。-->
++    <Target Name="_WalterlvDemoImportInWpfTempProject"
++            AfterTargets="MarkupCompilePass1"
++            BeforeTargets="GenerateTemporaryTargetAssembly"
++            DependsOnTargets="$(_WalterlvDemoImportInWpfTempProjectDependsOn)"
++            Condition=" ‘$(ShouldFixNuGetImportingBugForWpfProjects)‘ == ‘True‘ ">
++      <ItemGroup>
++        <_GeneratedCodeFiles Include="@(_WalterlvDemoAllCompile)" />
++      </ItemGroup>
++      <Message Text="3. 正在欺騙臨時專案，誤以為此 NuGet 包中的檔案是 XAML 編譯後的中間程式碼：@(_WalterlvDemoAllCompile)" />
++    </Target>

    </Project>

我們增加了 _WalterlvDemoImportInWpfTempProjectDependsOn 屬性，這個屬性裡面將填寫一個到多個編譯目標（Target）的名稱（多個用分號分隔），用於告知 _WalterlvDemoImportInWpfTempProject 這個編譯目標在執行之前必須確保執行的依賴編譯目標。而我們目前的依賴目標只有一個，就是 _WalterlvDemoIncludeSourceFiles 這個引入 C# 原始碼的編譯目標。如果你有其他考慮有引入更多 C# 原始碼的編譯目標，則需要把他們都加上（當然本文是不需要的）。為此，我還新增了一個 _WalterlvDemoAllCompile 集合，如果存在多個依賴的編譯目標會引入 C# 原始碼，則需要像 _WalterlvDemoIncludeSourceFiles 一樣，將他們都加入到 Compile 的同時也加入到 _WalterlvDemoAllCompile 集合中。

為什麼可能有多個引入 C# 原始碼的編譯目標？因為本文我們只考慮了引入我們提前準備好的原始碼放入原始碼包中，而我們提到過可能涉及到動態生成 C# 原始碼的需求。如果你有一兩個編譯目標會動態生成一些 C# 原始碼並將其加入到 Compile 集合中，那麼請將這個編譯目標的名稱加入到 _WalterlvDemoImportInWpfTempProjectDependsOn 屬性（注意多個用分號分隔），同時將集合也引入一份到 _WalterlvDemoAllCompile 中。

_WalterlvDemoIncludeWpfFiles 這個編譯目標的作用是引入 WPF 的 XAML 檔案，這很容易理解，畢竟我們的原始碼中包含 WPF 相關的檔案。

請特別注意：

1. 我們加了一個 Link 屬性，並且將其指定為 %(_WalterlvDemoPage.FileName).xaml。這意味著我們會把所有的 XAML 檔案都當作在專案根目錄中生成，如果你在其他的專案中用到了相對或絕對的 XAML 檔案的路徑，這顯然會改變路徑。但是，我們沒有其他的方法來根據 XAML 檔案所在的目錄層級來自定指定 Link 屬性讓其在正確的層級上，所以這裡才寫死在根目錄中。
   • 如果要解決這個問題，我們就需要在生成 NuGet 包之前生成此專案中所有 XAML 檔案的正確的 Link 屬性（例如改為 Views\%(_WalterlvDemoPage.FileName).xaml），這意味著需要在此專案編譯期間執行一段程式碼，把 Package.targets 檔案中為所有的 XAML 檔案生成正確的 Link 屬性。本文暫時不考慮這個問題，但你可以參考 dotnet-campus/SourceYard 專案來了解如何動態生成 Link。
2. 我們使用了 _WalterlvDemoPage 集合中轉地存了 XAML 檔案，這是必要的。因為這樣才能正確通過 % 符號獲取到 FileName 屬性。

而 _WalterlvDemoImportInWpfTempProject 這個編譯目標就不那麼好理解了，而這個也是完美支援 WPF 專案原始碼包的關鍵編譯目標！這個編譯目標指定在 MarkupCompilePass1 之後，GenerateTemporaryTargetAssembly 之前執行。GenerateTemporaryTargetAssembly 編譯目標的作用是生成一個臨時的專案，用於讓 WPF 的 XAML 檔案能夠依賴同項目的 .NET 型別而編譯。然而此臨時專案編譯期間是不會匯入任何 NuGet 的 props 或 targets 檔案的，這意味著我們特別新增的所有 C# 原始碼在這個臨時專案當中都是不存在的——如果專案使用到了我們原始碼包中的原始碼，那麼必然因為型別不存在而無法編譯通過——臨時專案沒有編譯通過，那麼整個專案也就無法編譯通過。但是，我們通過在 MarkupCompilePass1 和 GenerateTemporaryTargetAssembly 之間將我們原始碼包中的所有原始碼加入到 _GeneratedCodeFiles 集合中，即可將這些檔案加入到臨時專案中一起編譯。而原本 _GeneratedCodeFiles 集合中是什麼呢？就是大家熟悉的 XAML 轉換而成的 xxx.g.cs 檔案。

測試和釋出原始碼包

現在我們再次編譯這個專案，你將得到一個支援 WPF 專案的 NuGet 原始碼包。

完整專案結構和原始碼

至此，我們已經完成了編寫一個 NuGet 原始碼包所需的全部原始碼。接下來你可以在專案中新增更多的原始碼，這樣打出來的原始碼包也將包含更多原始碼。由於我們將將 XAML 檔案都通過 Link 屬性指定到根目錄了，所以如果你需要新增 XAML 檔案，你將只能新增到我們專案中的 Assets\src 目錄下，除非做 dotnet-campus/SourceYard 中類似的動態 Link 生成的處理，或者在 Package.targets 檔案中手工為每一個 XAML 編寫一個特別的 Link 屬性。

另外，在不改變我們整體專案結構的情況下，你也可以任意新增 WPF 所需的圖片資源等。但也需要在 Package.targets 中新增額外的 Resource 引用。如果沒有 dotnet-campus/SourceYard 的自動生成程式碼，你可能也需要手工編寫 Resource。

接下來我會貼出更復雜的程式碼，用於處理更復雜的原始碼包的場景。

目錄結構

更復雜原始碼包的專案組織形式會是下面這樣圖這樣：

我們在 Assets 資料夾中新增了一個 assets 資料夾。由於資源在此專案中的路徑必須和安裝後的目標專案中一樣才可以正確用 Uri 的方式使用資源，所以我們在專案檔案 csproj 和編譯檔案 Package.targets 中都對這兩個檔案設定了 Link 到同一個資料夾中，這樣才可以確保兩邊都能正常使用。

我們在 src 資料夾的不同子資料夾中建立了 XAML 檔案。按照我們前面的說法，我們也需要像資原始檔一樣正確在 Package.targets 中設定 Link 才可以確保 Uri 是一致的。注意，我們接下來的原始碼中沒有在專案檔案中設定 Link，原則上也是需要設定的，就像資源一樣，這樣才可以確保此專案和安裝此 NuGet 包中的目標專案具有相同的 XAML Uri。此例子只是因為沒有程式碼使用到了 XAML 檔案的路徑，所以才能得以倖免。

我們還利用了 tools 資料夾。我們在專案檔案的末尾將輸出檔案拷貝到了 tools 目錄下，這樣，我們專案的 Assets 資料夾幾乎與最終的 NuGet 包的資料夾結構一模一樣，非常利於除錯。但為了防止將生成的檔案上傳到版本管理，我在 tools 中添加了 .gitignore 檔案：

/net*/*

專案檔案

--  <Project Sdk="Microsoft.NET.Sdk">
++  <Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">
    
      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net48</TargetFramework>
++      <UseWpf>True</UseWpf>
    
        <!-- 要求此專案編譯時要生成一個 NuGet 包。-->
        <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
    
        <!-- 這裡為了方便，我將 NuGet 包的輸出路徑設定在瞭解決方案根目錄的 bin 資料夾下，而不是專案的 bin 資料夾下。-->
        <PackageOutputPath>..\bin\$(Configuration)</PackageOutputPath>
    
        <!-- 建立 NuGet 包時，專案的輸出檔案對應到 NuGet 包的 tools 資料夾，這可以避免目標專案引用我們的 NuGet 包的輸出檔案。
             同時，如果將來我們準備動態生成原始碼，而不只是引入靜態原始碼，還可以有機會執行我們 Program 中的 Main 函式。-->
        <BuildOutputTargetFolder>tools</BuildOutputTargetFolder>
    
        <!-- 此包將不會傳遞依賴。意味著如果目標專案安裝了此 NuGet 包，那麼安裝目標專案包的專案不會間接安裝此 NuGet 包。-->
        <DevelopmentDependency>true</DevelopmentDependency>
    
        <!-- 包的版本號，我們設成了一個預覽版；當然你也可以設定為正式版，即沒有後面的 -alpha 字尾。-->
        <Version>0.1.0-alpha</Version>
    
        <!-- 設定包的作者。在上傳到 nuget.org 之後，如果作者名與 nuget.org 上的賬號名相同，其他人瀏覽包是可以直接點選連結看作者頁面。-->
        <Authors>walterlv</Authors>
    
        <!-- 設定包的組織名稱。我當然寫成我所在的組織 dotnet 職業技術學院啦。-->
        <Company>dotnet-campus</Company>
      </PropertyGroup>
    
++    <!-- 我們新增的其他資源需要在這裡 Link 到一個統一的目錄下，以便在此專案和安裝 NuGet 包的目標專案中可以用同樣的 Uri 使用。 -->
++    <ItemGroup>
++      <Resource Include="Assets\assets\Icon.ico" Link="Assets\Icon.ico" Visible="False" />
++      <Resource Include="Assets\assets\Background.png" Link="Assets\Background.png" Visible="False" />
++    </ItemGroup>
      
      <!-- 在生成 NuGet 包之前，我們需要將我們專案中的資料夾結構一一對映到 NuGet 包中。-->
      <Target Name="IncludeAllDependencies" BeforeTargets="_GetPackageFiles">
        <ItemGroup>
    
          <!-- 將 Package.props / Package.targets 檔案的名稱在 NuGet 包中改為需要的真正名稱。
               因為 NuGet 包要自動匯入 props 和 targets 檔案，要求檔案的名稱必須是 包名.props 和 包名.targets；
               然而為了避免我們改包名的時候還要同步改四個檔案的名稱，所以就在專案檔案中動態生成。-->
          <None Include="Assets\build\Package.props" Pack="True" PackagePath="build\$(PackageId).props" />
          <None Include="Assets\build\Package.targets" Pack="True" PackagePath="build\$(PackageId).targets" />
          <None Include="Assets\buildMultiTargeting\Package.props" Pack="True" PackagePath="buildMultiTargeting\$(PackageId).props" />
          <None Include="Assets\buildMultiTargeting\Package.targets" Pack="True" PackagePath="buildMultiTargeting\$(PackageId).targets" />
    
          <!-- 我們將 src 目錄中的所有原始碼對映到 NuGet 包中的 src 目錄中。-->
          <None Include="Assets\src\**" Pack="True" PackagePath="src" />

++        <!-- 我們將 assets 目錄中的所有原始碼對映到 NuGet 包中的 assets 目錄中。-->
++        <None Include="Assets\assets\**" Pack="True" PackagePath="assets" />
    
        </ItemGroup>
      </Target>
    
++    <!-- 在編譯結束後將生成的可執行程式放到 Tools 資料夾中，使得 Assets 資料夾的目錄結構與 NuGet 包非常相似，便於 Sample 專案進行及時的 NuGet 包除錯。 -->
++    <Target Name="_WalterlvDemoCopyOutputToDebuggableFolder" AfterTargets="AfterBuild">
++        <ItemGroup>
++        <_WalterlvDemoToCopiedFiles Include="$(OutputPath)**" />
++        </ItemGroup>
++        <Copy SourceFiles="@(_WalterlvDemoToCopiedFiles)" DestinationFolder="Assets\tools\$(TargetFramework)" />
++    </Target>

    </Project>

編譯檔案

    <Project>
    
      <PropertyGroup>
        <MSBuildAllProjects>$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>
      </PropertyGroup>
    
      <PropertyGroup>
        <!-- 我們增加了一個屬性，用於處理 WPF 特殊專案的原始碼之前，確保我們已經收集到所有需要引入的原始碼。 -->
        <_WalterlvDemoImportInWpfTempProjectDependsOn>_WalterlvDemoIncludeSourceFiles</_WalterlvDemoImportInWpfTempProjectDependsOn>
      </PropertyGroup>
      
      <Target Name="_WalterlvDemoEvaluateProperties">
        <PropertyGroup>
          <_WalterlvDemoRoot>$(MSBuildThisFileDirectory)..\</_WalterlvDemoRoot>
          <_WalterlvDemoSourceFolder>$(MSBuildThisFileDirectory)..\src\</_WalterlvDemoSourceFolder>
        </PropertyGroup>
        <Message Text="1. 初始化原始碼包的編譯屬性" />
      </Target>
    
      <!-- 引入主要的 C# 原始碼。 -->
      <Target Name="_WalterlvDemoIncludeSourceFiles"
              BeforeTargets="CoreCompile"
              DependsOnTargets="_WalterlvDemoEvaluateProperties">
        <ItemGroup>
          <_WalterlvDemoCompile Include="$(_WalterlvDemoSourceFolder)**\*.cs" />
          <_WalterlvDemoAllCompile Include="@(_WalterlvDemoCompile)" />
          <Compile Include="@(_WalterlvDemoCompile)" />
        </ItemGroup>
        <Message Text="2.1 引入原始碼包中的所有原始碼：@(_WalterlvDemoCompile)" />
      </Target>
    
      <!-- 引入 WPF 原始碼。 -->
      <Target Name="_WalterlvDemoIncludeWpfFiles"
              BeforeTargets="MarkupCompilePass1"
              DependsOnTargets="_WalterlvDemoEvaluateProperties">
        <ItemGroup>
--        <_WalterlvDemoPage Include="$(_WalterlvDemoSourceFolder)**\*.xaml" />
--        <Page Include="@(_WalterlvDemoPage)" Link="Views\%(_WalterlvDemoPage.FileName).xaml" />
++        <_WalterlvDemoRootPage Include="$(_WalterlvDemoSourceFolder)FooView.xaml" />
++        <Page Include="@(_WalterlvDemoRootPage)" Link="Views\%(_WalterlvDemoRootPage.FileName).xaml" />
++        <_WalterlvDemoThemesPage Include="$(_WalterlvDemoSourceFolder)Themes\Walterlv.Windows.xaml" />
++        <Page Include="@(_WalterlvDemoThemesPage)" Link="Views\%(_WalterlvDemoThemesPage.FileName).xaml" />
++        <_WalterlvDemoIcoResource Include="$(_WalterlvDemoRoot)assets\*.ico" />
++        <_WalterlvDemoPngResource Include="$(_WalterlvDemoRoot)assets\*.png" />
++        <Resource Include="@(_WalterlvDemoIcoResource)" Link="assets\%(_WalterlvDemoIcoResource.FileName).ico" />
++        <Resource Include="@(_WalterlvDemoPngResource)" Link="assets\%(_WalterlvDemoPngResource.FileName).png" />
        </ItemGroup>
--      <Message Text="2.2 引用 WPF 相關原始碼：@(_WalterlvDemoPage);@(_WalterlvDemoIcoResource);@(_WalterlvDemoPngResource)" />
++      <Message Text="2.2 引用 WPF 相關原始碼：@(_WalterlvDemoRootPage);@(_WalterlvDemoThemesPage);@(_WalterlvDemoIcoResource);@(_WalterlvDemoPngResource)" />
      </Target>
    
      <!-- 當生成 WPF 臨時專案時，不會自動 Import NuGet 中的 props 和 targets 檔案，這使得在臨時專案中你現在看到的整個檔案都不會參與編譯。
           然而，我們可以通過欺騙的方式在主專案中通過 _GeneratedCodeFiles 集合將需要編譯的檔案傳遞到臨時專案中以間接參與編譯。
           WPF 臨時專案不會 Import NuGet 中的 props 和 targets 可能是 WPF 的 Bug，也可能是刻意如此。
           所以我們通過一個屬性開關 `ShouldFixNuGetImportingBugForWpfProjects` 來決定是否修復這個錯誤。-->
      <Target Name="_WalterlvDemoImportInWpfTempProject"
              AfterTargets="MarkupCompilePass1"
              BeforeTargets="GenerateTemporaryTargetAssembly"
              DependsOnTargets="$(_WalterlvDemoImportInWpfTempProjectDependsOn)"
              Condition=" ‘$(ShouldFixNuGetImportingBugForWpfProjects)‘ == ‘True‘ ">
        <ItemGroup>
          <_GeneratedCodeFiles Include="@(_WalterlvDemoAllCompile)" />
        </ItemGroup>
        <Message Text="3. 正在欺騙臨時專案，誤以為此 NuGet 包中的檔案是 XAML 編譯後的中間程式碼：@(_WalterlvDemoAllCompile)" />
      </Target>
    
    </Project>

開源專案

本文涉及到的所有程式碼均已開源到：

• walterlv.demo/Walterlv.PackageDemo at master · walterlv/walterlv.demo

更多內容

SourceYard 開源專案

本文服務於開源專案 SourceYard，為其提供支援 WPF 專案的解決方案。dotnet-campus/SourceYard: Add a NuGet package only for dll reference? By using dotnetCampus.SourceYard,you can pack a NuGet package with source code. By installing the new source code package,all source codes behaviors just like it is in your project.

相關部落格

更多製作原始碼包的部落格可以閱讀。從簡單到複雜的順序：

• 將 .NET Core 專案打一個最簡單的 NuGet 原始碼包，安裝此包就像直接把原始碼放進專案一樣 - 呂毅
• Roslyn 如何基於 Microsoft.NET.Sdk 製作原始碼包 - 林德熙
• 製作通過 NuGet 分發的原始碼包時，如果目標專案是 WPF 則會出現一些問題（探索篇，含解決方案） - 呂毅
• SourceYard 製作原始碼包 - 林德熙

本文會經常更新，請閱讀原文： https://blog.walterlv.com/post/build-source-code-package-for-wpf-projects.html ，以避免陳舊錯誤知識的誤導，同時有更好的閱讀體驗。

如果你想持續閱讀我的最新部落格，請點選 RSS 訂閱，或者前往 CSDN 關注我的主頁。

本作品採用 知識共享署名-非商業性使用-相同方式共享 4.0 國際許可協議 進行許可。歡迎轉載、使用、重新發布，但務必保留文章署名 呂毅 （包含連結： https://blog.walterlv.com ），不得用於商業目的，基於本文修改後的作品務必以相同的許可釋出。如有任何疑問，請 與我聯絡 ([email protected]) 。

出處：https://blog.walterlv.com/post/build-source-code-package-for-wpf-projects.html

=========================================================================================

2019-06-16 12:53

預設情況下，我們打包 NuGet 包時，目標專案安裝我們的 NuGet 包會引用我們生成的庫檔案（dll）。除此之外，我們也可以專門做 NuGet 工具包，還可以做 NuGet 原始碼包。然而做原始碼包可能是其中最困難的一種了，目標專案安裝完後，這些原始碼將直接隨目標專案一起編譯。

本文將從零開始，教你製作一個支援 .NET 各種型別專案的原始碼包。

本文內容

• 前置知識
• 製作一個原始碼包
  • 第一步：建立一個 .NET 專案
  • 第二步：組織專案的目錄結構
  • 第三步：編寫專案檔案 csproj
  • 第四步：編寫編譯檔案 targets
    • buildMultiTargeting 資料夾中的 Package.props 檔案
    • buildMultiTargeting 資料夾中的 Package.targets 檔案
    • build 資料夾中的 Package.props 檔案
    • build 資料夾中的 Package.targets 檔案
    • 這四個檔案分別的作用
    • 體驗和檢視 NuGet 原始碼包
  • 第五步：加入 WPF 專案支援
    • build 資料夾中的 Package.props 檔案
    • build 資料夾中的 Package.targets 檔案
  • 測試和釋出原始碼包
• 完整專案結構和原始碼
  • 目錄結構
  • 專案檔案
  • 編譯檔案
  • 開源專案
• 更多內容
  • SourceYard 開源專案
  • 相關部落格

前置知識

在開始製作一個原始碼包之間，建議你提前瞭解專案檔案的一些基本概念：

• 理解 C# 專案 csproj 檔案格式的本質和編譯流程

當然就算不了解也沒有關係。跟著本教程你也可以製作出來一個原始碼包，只不過可能遇到了問題的時候不容易除錯和解決。

製作一個原始碼包

接下來，我們將從零開始製作一個原始碼包。

我們接下來的將建立一個完整的解決方案，這個解決方案包括：

1. 一個將打包成原始碼包的專案
2. 一個除錯專用的專案（可選）
3. 一個測試原始碼包的專案（可選）

第一步：建立一個 .NET 專案

像其他 NuGet 包的引用專案一樣，我們需要建立一個空的專案。不過差別是我們需要建立的是控制檯程式。

當建立好之後，Main 函式中的所有內容都是不需要的，於是我們刪除 Main 函式中的所有內容但保留 Main 函式。

這時 Program.cs 中的內容如下：

namespace Walterlv.PackageDemo.SourceCode
{
    class Program
    {
        static void Main(string[] args)
        {
        }
    }
}

雙擊建立好的專案的專案，或者右鍵專案 “編輯專案檔案”，我們可以編輯此專案的 csproj 檔案。

在這裡，我將目標框架改成了 net48。實際上如果我們不製作動態原始碼生成，那麼這裡無論填寫什麼目標框架都不重要。在這篇部落格中，我們主要篇幅都會是做靜態原始碼生成，所以你大可不必關心這裡填什麼。

提示：如果 net48 讓你無法編譯這個專案，說明你電腦上沒有裝 .NET Framework 4.8 框架，請改成 net473,all source codes behaviors just like it is in your project.

%~dp0nuget.exe pack %~dp0Package.nuspec -OutputDirectory %~dp0

PM> Get-Help nuget
TOPIC
    about_NuGet
    
SHORT DESCRIPTION
    Provides information about NuGet Package Manager commands.
           
LONG DESCRIPTION
    This topic describes the NuGet Package Manager commands. NuGet is an integrated package 
    management tool for adding libraries and tools to .NET projects.

                 
    The following NuGet cmdlets are included.

        Cmdlet					Description
        ------------------		----------------------------------------------
        Get-Package				Gets the set of installed packages.  With -ListAvailable,gets the set of packages available from the package source.

        Install-Package			Installs a package and its dependencies into the project.

        Uninstall-Package		Uninstalls a package. If other packages depend on this package,the command will fail unless the –Force option is specified.

        Update-Package			Updates a package and its dependencies to a newer version.

        Add-BindingRedirect		Examines all assemblies within the output path for a project
                                and adds binding redirects to the application (or web) 
                                configuration file where necessary.
                            
        Get-Project				Returns a reference to the DTE (Development Tools Environment) 
                                for the specified project. If none is specifed,returns the 
                                default project selected in the Package Manager Console.

        Open-PackagePage        Open the browser pointing to ProjectUrl,LicenseUrl or 
                                ReportAbuseUrl of the specified package.

        Register-TabExpansion	Registers a tab expansion for the parameters of a command.

SEE ALSO
    Online documentation: http://go.microsoft.com/fwlink/?LinkID=206619
    Get-Package
    Install-Package
    Uninstall-Package
    Update-Package
    Add-BindingRedirect
    Get-Project
    Open-PackagePage
    Register-TabExpansion

PM> Install-Package AsyncModule.NetMQ
Attempting to resolve dependency ‘NetMQ (≥ 4.0.0.1)‘.
Attempting to resolve dependency ‘AsyncIO (≥ 0.1.26)‘.
Installing ‘AsyncIO 0.1.26.0‘.
Successfully installed ‘AsyncIO 0.1.26.0‘.
Installing ‘NetMQ 4.0.0.1‘.
Successfully installed ‘NetMQ 4.0.0.1‘.
Installing ‘AsyncModule.NetMQ 1.1.0‘.
Successfully installed ‘AsyncModule.NetMQ 1.1.0‘.
Adding ‘AsyncIO 0.1.26.0‘ to NuGet.Client.
Successfully added ‘AsyncIO 0.1.26.0‘ to NuGet.Client.
Adding ‘NetMQ 4.0.0.1‘ to NuGet.Client.
Successfully added ‘NetMQ 4.0.0.1‘ to NuGet.Client.
Adding ‘AsyncModule.NetMQ 1.1.0‘ to NuGet.Client.
Successfully added ‘AsyncModule.NetMQ 1.1.0‘ to NuGet.Client.

PM> Get-Package

Id                             Version              Description/Release Notes                                                                                                                                     
--                             -------              -------------------------                                                                                                                                     
AsyncIO                        0.1.26.0             AsyncIO                                                                                                                                                       
AsyncModule.NetMQ              1.1.0                基於NetMQ的非同步Socket框架                                                                                                                                            
NetMQ                          4.0.0.1              A 100% native C# port of the lightweight high performance messaging library ZeroMQ                                                                            

PM> Uninstall-Package AsyncModule.NetMQ
Removing ‘AsyncModule.NetMQ 1.1.0‘ from NuGet.Client.
Successfully removed ‘AsyncModule.NetMQ 1.1.0‘ from NuGet.Client.
Uninstalling ‘AsyncModule.NetMQ 1.1.0‘.
Successfully uninstalled ‘AsyncModule.NetMQ 1.1.0‘.

PM> Install-Package AsyncModule.NetMQ -Version 1.1.0
Attempting to resolve dependency ‘NetMQ (≥ 4.0.0.1)‘.
Attempting to resolve dependency ‘AsyncIO (≥ 0.1.26)‘.
Installing ‘AsyncModule.NetMQ 1.1.0‘.
Successfully installed ‘AsyncModule.NetMQ 1.1.0‘.
Adding ‘AsyncModule.NetMQ 1.1.0‘ to NuGet.Client.
Successfully added ‘AsyncModule.NetMQ 1.1.0‘ to NuGet.Client.

    <BuildPackage>true</BuildPackage>
    <RestorePackages>true</RestorePackages>

<Import Project="$(SolutionDir)\.nuget\NuGet.targets" Condition="Exists(‘$(SolutionDir)\.nuget\NuGet.targets‘)" />
  <Target Name="EnsureNuGetPackageBuildImports" BeforeTargets="PrepareForBuild">
    <PropertyGroup>
      <ErrorText>This project references NuGet package(s) that are missing on this computer. Enable NuGet Package Restore to download them.  For more information,see http://go.microsoft.com/fwlink/?LinkID=322105. The missing file is {0}.</ErrorText>
    </PropertyGroup>
    <Error Condition="!Exists(‘$(SolutionDir)\.nuget\NuGet.targets‘)" Text="$([System.String]::Format(‘$(ErrorText)‘,‘$(SolutionDir)\.nuget\NuGet.targets‘))" />
  </Target>

PM> Install-Package NuGet.Server

nuget.exe push {package file} {apikey} -Source http://www.jnuget.com:10080/nuget