在 .NET 專案引用動態連結程式庫(DLL)的正確方式

TLDR

• 優先使用 NuGet 管理套件，以解決版本控制、Framework 相容性及相依性管理問題。
• 若必須引用本機 DLL，請建立專屬資料夾（非 bin 目錄）存放，並將該資料夾納入版控。
• 嚴禁直接引用 bin 目錄下的 DLL，這會導致編譯時因來源遺失而失敗，且無法統一管理版本。
• Website Project (WSP) 需將自動產生的 .dll.refresh 檔案納入版控，以確保引用來源正確。

為什麼應優先使用 NuGet 管理套件

在 .NET 專案中，直接引用 DLL 檔案並非最佳實踐。建議優先使用 NuGet 進行管理，原因如下：

• 升降版操作簡便。
• NuGet 可自動處理 Framework 相容性，並根據專案設定下載最適合的版本。
• 自動解決套件之間的相依性問題，安裝時會一併下載所需的相依套件。
• 若為公司內部 Library，建議架設私有 NuGet Server，將 Library 打包為 NuGet 套件後進行管理。

本機 DLL 的正確引用方式

當無法使用 NuGet 而必須引用本機 DLL 時，應採取以下步驟以確保協作順暢：

1. 在方案目錄下建立一個專屬資料夾（建議命名避免與 packages 混淆）。
2. 將所有需要引用的 DLL 檔案統一放置於該資料夾中。
3. 專案參考路徑皆指向此資料夾。
4. 必須將此資料夾納入版控系統，確保團隊成員皆能取得相同的 DLL 檔案。

的正確方式/nuget-packages-folder-reference.png)

直接引用 bin 目錄的風險

什麼情況下會遇到這個問題：開發者為了方便，直接將 DLL 複製到編譯輸出目錄 bin 並從該處進行引用。

• 編譯失敗風險：bin 目錄通常不納入版控。若將 DLL 放在 bin 下引用，當清理專案或刪除 bin 目錄後，專案檔（.csproj）記錄的來源路徑將會失效，導致無法重新建置。
• 版本管理混亂：若同方案下有多個專案，各自引用 bin 目錄下的 DLL，容易導致不同專案引用到不同版本的 DLL，難以控管。

的正確方式/bin-folder-missing-reference.png)

Website Project (WSP) 的特殊處理

什麼情況下會遇到這個問題：使用 Website Project (WSP) 類型專案，因其缺乏傳統專案檔（.csproj），需透過特殊機制記錄引用來源。

WSP 在加入參考時，會於 bin 目錄下產生一個 {DLL名稱}.dll.refresh 檔案。該檔案內部記錄了 DLL 的實際引用來源路徑。

TIP

雖然 bin 目錄本身不建議納入版控，但其中的 .dll.refresh 檔案必須納入版控，以確保其他開發者在還原專案時，能正確識別 DLL 的引用來源。

的正確方式/dll-refresh-file.png) 的正確方式/dll-refresh-content.png)

異動歷程

• 2022-09-30 初版文件建立。