舊式 C# 專案最難追的建置問題，通常不是語法錯誤，而是專案檔描述的建置圖與儲存庫內容已經分離：原始碼存在卻未列入 Compile、組件參考指向已消失的 HintPath、單獨建置 .csproj 時又假設 SolutionDir 一定存在。這些缺口可能被舊的 bin、共用輸出目錄或另一個專案留下的 DLL 暫時遮住，於是同一版程式在不同電腦、不同輸出資料夾或第二次建置時出現互相矛盾的結果。

本文提供一套 MSBuild 專案完整性 檢查方法：先把原始碼、專案參考與建置屬性視為三個獨立契約，再用乾淨輸出與隔離路徑逐層驗證。搜尋意圖屬資訊型與問題排除型，位於 MOFU；North Star Metric 是「乾淨環境首次建置通過率」，輔助 KPI 包含未解析參考數、漏列編譯項目數、依賴殘留輸出的建置比例，以及單建專案造成的儲存庫污染數。

為什麼檔案已在資料夾內，舊式 csproj 還是可能找不到型別？

MSBuild 專案完整性首先要確認來源成員：舊式專案是否編譯某支 C# 檔，取決於專案評估後的 Compile 項目，而不是檔案總管裡看得到它；只提交 .cs 而漏掉專案檔變更，編譯器便不會收到該檔案。

Microsoft 的 .NET SDK 文件說明，較新的 SDK-style 專案預設會從專案目錄包含 Compile glob，因此一般不必逐檔列出；同一份文件也提供 EnableDefaultCompileItems，可停用預設編譯項目。這個對照很重要：看到「檔案放進資料夾就會自動編譯」的經驗，不能直接套用到明確列舉 `` 的舊式專案。

問題的典型演進如下：開發者新增命名空間與三支類別，呼叫端也提交完成，但 .csproj 沒有新增相對應項目。其他人拉取後得到 CS0234、CS0246 或 CS0103，直覺上會懷疑套件、using 或 IDE 快取；其實編譯器根本沒看見那些來源。最有效的第一步不是重裝工具，而是檢查預處理後的專案與實際 Compile 清單。

對舊式專案，可以用版本控制歷史確認「類別加入」與「專案檔加入」是否同步。若原始碼提交存在，而專案檔從未出現該路徑，問題就是來源成員資格缺漏。修正時應加入精確相對路徑，避免用過寬 glob 把備份檔、產生檔或不應編譯的實驗檔一起納入。

變更後不要只按 IDE 的 Build。先刪除隔離測試目錄內的 bin 與 obj，再從命令列建置，並確認錯誤是從「找不到型別」變成零退出。若專案檔需保留 BOM 與 CRLF，也應在提交前檢查編碼及行尾，避免一個兩行修正變成整份檔案重寫，增加審查與合併衝突成本。

為什麼失效 HintPath 有時第一次失敗、第二次卻成功？

HintPath 只是 MSBuild 解析組件時使用的候選位置；當它已失效，髒的輸出目錄、其他專案先複製的同名 DLL 或搜尋路徑仍可能讓建置暫時通過，因此重複建置不是可靠證據。

MSBuild 的 Reference 項目支援 HintPath，用來提供組件檔案的相對或絕對位置；Microsoft 的組件參考疑難排解文件則建議使用 -bl 產生 binary log，查看 ResolveAssemblyReference 如何搜尋候選路徑。兩者合起來的結論是：專案檔寫了某個路徑，不代表解析器最後一定使用它，也不代表該檔案仍存在。

最危險的情境是所有專案共用一個 OutDir。專案 A 先把 DLL 複製進去，專案 B 的失效 HintPath 便可能在後續解析時撿到同名檔；換成全新資料夾後，遮蔽物消失，真正的未解析參考才會出現。這也解釋了為什麼「第二次 build 過了」反而是一個警訊：建置結果依賴前一次留下的狀態，而不是只依賴受控輸入。

若被參考的程式庫與呼叫端都在同一個解決方案或可用的來源樹中，通常應優先評估 ProjectReference。Microsoft 的 MSBuild common items 文件指出，ProjectReference 表示另一個專案的參考；建置系統可依相依關係先建被參考專案，再把輸出提供給呼叫端。這比指向某個開發者工作區或已不存在 sibling 目錄的 DLL 路徑，更能表達真正的建置圖。

但不能把所有 DLL 參考無條件改成專案參考。若呼叫端的正式契約本來就是經審核的二進位或套件，就應修正到可重現的產物位置，並驗證版本、雜湊與 Copy Local。決策關鍵是「建置輸入的擁有者是誰」：同一來源圖使用 ProjectReference；外部發行邊界使用版本化套件或受控檔案參考。不要用髒輸出掩蓋所有權不清。

單獨建置 csproj 時，SolutionDir 為什麼不能當成永遠存在？

SolutionDir 是解決方案層級的巨集；所附舊版 Build Events 文件定義它為解決方案目錄，並未保證直接建置專案時可用；不要把巨集表當成所有工具鏈的初始化保證。直接建置專案若仍把它用於 post-build copy，路徑可能為空或未定義。

舊式專案常在 post-build event 中把 $(TargetPath) 複製到 $(SolutionDir)Libraries\Internal。從 .sln 建置時看似正常，改成單建 .csproj、測試單一專案或由工具注入 OutDir 後，該屬性便沒有可靠來源。最差的結果不只是 copy 失敗；若腳本對空路徑處理不嚴格，還可能寫入非預期位置或覆蓋儲存庫中的已追蹤產物。

安全做法有三層。第一，能移除 post-build 複製就移除，改由專案相依、打包或發布流程管理產物。第二，若舊流程暫時不能改，目標應先對空值與路徑邊界 fail closed。第三，在單建驗證時，明確傳入位於 sandbox 的 SolutionDir 與 OutDir，讓必要的副作用只落在可拋棄目錄。

dotnet msbuild SolutionDirProbe.proj -nologo -v:minimal
dotnet msbuild SolutionDirProbe.proj -nologo -v:minimal \
  -p:SolutionDir="C:/sandbox/build-root/" \
  -p:OutDir="C:/sandbox/output/"

不要把真實解決方案根目錄直接當成探針輸出。驗證的目的，是確認屬性缺失時會明確失敗、屬性被安全指定時才寫入隔離位置，而不是順手更新工作區中的 DLL。建置後再檢查版本控制狀態，若出現新的已修改或未追蹤產物，就代表建置仍有超出 sandbox 的副作用。

如何設計不被殘留輸出欺騙的乾淨建置？

可靠的乾淨建置要為每個被驗證專案配置新的輸出與中介目錄，禁止從共用舊目錄借檔，並把警告、實際解析路徑與版本控制狀態都列為驗收證據。

只執行 Clean 不一定等於乾淨，因為自訂 copy、共用 OutDir、外部 Libraries 目錄與手動留下的檔案可能不在標準清理範圍。較可信的方法是為每次驗證建立全新 sandbox，將輸出導向唯一子目錄，並在建置前確認目標不存在。若要查組件解析，加入 -bl 產生 binary log，再用 MSBuild Structured Log Viewer 檢查 ResolveAssemblyReference 的搜尋順序與最終來源。

驗收應同時檢查：

  • 所有預期 .cs 都出現在評估後的 Compile 項目。
  • 每個必要組件來自核准位置，不是先前建置的偶然殘留。
  • 未解析參考警告視為失敗，不以最後是否產生 DLL 判定。
  • ProjectReference 的被參考專案確實先建置，輸出也進入呼叫端目錄。
  • post-build event 只寫入隔離根目錄，沒有修改儲存庫。
  • 第一次與第二次建置結果一致；若只有第二次成功，要停止並找出被借用的產物。

這些檢查比「在我的電腦可建」更接近可重現契約。團隊可以把每個建置輸入分為來源專案、版本化套件、受控二進位三類，禁止第四種「不知道從哪個資料夾撿到的同名 DLL」。一旦來源分類清楚，修復優先順序也會清楚：漏 Compile 補專案成員；錯誤 ownership 改 ProjectReference；外部邊界則修正套件或受控 HintPath。

驗證與重現：固定 .NET 10 的隔離 MSBuild 測試

本次以 .NET SDK 10.0.400 在 Windows sandbox 實際執行六項測試，重現漏 Compile、失效 HintPath 與缺少 SolutionDir，再驗證相對應修正。

這個測試用 SDK-style 專案搭配 EnableDefaultCompileItems=false 模擬舊式逐檔列舉行為。它驗證的是 MSBuild 項目與參考契約，不宣稱已在排程環境重建任何私有 .NET Framework 專案，也不推論不同 Visual Studio 工具鏈的所有細節。

  1. 建立 global.json，固定 SDK 為 10.0.400，並在全新測試根目錄準備 Broken 與 Fixed 專案。
  2. 在 Broken 編譯專案中只列 Program.cs，保留實際存在但未列入的 MessageProvider.cs；執行建置並要求 CS0103 與非零退出。
  3. 在 Fixed 專案加入第二個 Compile 項目；重新建置並要求退出碼為零。
  4. 建立一個類別庫；讓 Broken 呼叫端以不存在的 HintPath 參考它，要求乾淨建置出現 CS0246；Fixed 呼叫端改用 ProjectReference，要求建置成功且輸出含被參考 DLL。
  5. 直接執行需要 SolutionDir 的 probe，要求缺少屬性時出現 SOLUTIONDIR_EMPTY；再傳入隔離路徑，要求 marker 只出現在 sandbox。
  6. 只有六項測試的預期退出碼、必要錯誤字串及輸出檔全部符合，整體才通過。

核心專案片段如下：


  
    Exe
    net10.0
    false

請先在全新測試根目錄依下列相對路徑建立完整檔案；內容與本次實際執行的 fixture 一致。

global.json

{
  "sdk": {
    "version": "10.0.400",
    "rollForward": "disable"
  }
}

CompileBroken/CompileBroken.csproj


  
    Exe
    net10.0
    disable
    enable
    false

CompileBroken/Program.cs

using System;

Console.WriteLine(MessageProvider.GetMessage());

CompileBroken/MessageProvider.cs

internal static class MessageProvider
{
    internal static string GetMessage() => "explicit compile item included";
}

CompileFixed/CompileFixed.csproj


  
    Exe
    net10.0
    disable
    enable
    false

CompileFixed/Program.cs

using System;

Console.WriteLine(MessageProvider.GetMessage());

CompileFixed/MessageProvider.cs

internal static class MessageProvider
{
    internal static string GetMessage() => "explicit compile item included";
}

BuildModel/BuildModel.csproj


  
    net10.0
    disable
    enable

BuildModel/BuildMessage.cs

namespace BuildModel;

public static class BuildMessage
{
    public static string Value => "project reference resolved";
}

ReferenceBroken/ReferenceBroken.csproj


  
    Exe
    net10.0
    disable
    enable
  
  
    
      ..\missing\BuildModel.dll

ReferenceBroken/Program.cs

using System;
using BuildModel;

Console.WriteLine(BuildMessage.Value);

ReferenceFixed/ReferenceFixed.csproj


  
    Exe
    net10.0
    disable
    enable

ReferenceFixed/Program.cs

using System;
using BuildModel;

Console.WriteLine(BuildMessage.Value);

SolutionDirProbe.proj

**探針邊界：**這個 probe 只拒絕空的 SolutionDir，不會驗證路徑是否位於 sandbox，也不會拒絕所有舊工具鏈的未定義標記。隔離路徑由測試呼叫端提供；它不是可直接部署的路徑防護元件。以下 C:/sandbox 路徑是示意，請替換成自己的全新隔離目錄，勿指定任何既有專案。前面的 OutDir 參數只是示範傳參，這個 probe 不會使用它。

執行命令（Windows Git Bash；預期失敗案例請逐條執行，不要用 && 串接）：

dotnet --version
dotnet build CompileBroken/CompileBroken.csproj --configuration Release --nologo --verbosity minimal
dotnet build CompileFixed/CompileFixed.csproj --configuration Release --nologo --verbosity minimal
dotnet build ReferenceBroken/ReferenceBroken.csproj --configuration Release --nologo --verbosity minimal
dotnet build ReferenceFixed/ReferenceFixed.csproj --configuration Release --nologo --verbosity minimal
dotnet msbuild SolutionDirProbe.proj -nologo -v:minimal
dotnet msbuild SolutionDirProbe.proj -nologo -v:minimal -p:SolutionDir="C:/sandbox/isolated-solution/"

預期驗收摘要（非逐字終端輸出）：

CompileBroken: exit 1, CS0103
CompileFixed: exit 0
ReferenceBroken: exit 1, MSB3245 and CS0246
ReferenceFixed: exit 0, BuildModel.dll present
SolutionDir absent: exit 1, SOLUTIONDIR_EMPTY
SolutionDir supplied: exit 0, SOLUTIONDIR_OK, probe.txt present

實際結果為六項全數符合：漏列 Compile 的專案以 CS0103 非零退出；補列後零退出；不存在的 HintPath 產生 MSB3245 警告及 CS0246 錯誤；ProjectReference 版本零退出且輸出資料夾存在 BuildModel.dll；未提供 SolutionDir 的 probe 以 SOLUTIONDIR_EMPTY 失敗；提供隔離 SolutionDir 後零退出並建立 marker。測試未呼叫業務服務，也未修改既有專案；dotnet build 的自動還原是否使用套件來源，不在這次測試的網路觀測範圍。

失敗判準必須維持嚴格：若 Broken 案例意外成功，表示仍有殘留輸入；若 Fixed 案例非零退出，修正尚未成立；若參考 DLL 不在呼叫端輸出，建置圖仍不完整；若 marker 出現在 sandbox 以外，路徑隔離失敗。這些條件比複製一段看似成功的終端輸出更重要。

修正前後的審查清單與決策原則

是否接受修正，取決於全新輸出下能否由受控來源重建同一結果，而不是 IDE 是否暫時不顯示紅線；任何依賴第二次建置或未知 DLL 的方案都應退回。

提交前逐項確認：

  • 新增或移動的 .cs 已同步反映在舊式專案的 Compile 項目。
  • 專案檔修改保留原有編碼、BOM 與行尾策略。
  • 每個 HintPath 的目標存在、受版本控制或由明確建置步驟產生。
  • 同一來源樹內的程式庫已評估改用 ProjectReference，且沒有循環參考。
  • 乾淨 OutDir 第一次建置即可通過，沒有借用 bin 或共用資料夾殘留。
  • 單建 .csproj 時不假設 SolutionDir 自動存在；必要時使用隔離值。
  • post-build copy 不會寫入工作區、覆蓋已追蹤 DLL 或擴大到未知路徑。
  • binary log 能指出每個關鍵組件的最終解析來源。
  • 建置前後版本控制狀態一致，只有預期的專案檔變更。

本文與既有「.NET DLL 部署驗證」的搜尋意圖不同：後者處理候選發布集合的版本、雜湊與執行載入一致性；本文處理編譯之前的專案圖是否完整，核心問題是漏 Compile、錯誤 HintPath 與解決方案屬性假設。它也不同於「GitLab IIS 部署」的 staging 與目錄切換，並不討論站台發布順序。

最終原則是：把專案檔當成可執行的建置規格，而不是 IDE 自動維護的附屬檔案。只要每支來源、每個參考與每項路徑屬性都有明確所有權，再以全新 sandbox 驗證第一次建置，這類「昨天可建、今天不可建」的幽靈問題就能被轉化為可重現、可審查的契約缺口。

官方查核來源與範圍

2026-10-17 重新開啟官方文件。保留原始 verifiedReferences 供來源稽核；其中 Build Events 舊版頁面只支持巨集定義，不支持原先 metadata 對定義時機的完整敘述。直接建置缺值的結果由本篇有限 probe 證實，不能外推為所有工具鏈的相同行為。