C# 組件開發完整教學：從建立 DLL 到命名空間管理與版本控制

什麼是組件？

組件是 .NET 部署、版本控制、安全性與類型標識的基本單位。以 .dll 或 .exe 形式存在，包含：

• 中間語言 (IL) 代碼
• 元數據（類型定義、成員簽名、屬性）
• 資訊清單（組件名稱、版本、文化特性、強名稱、檔案列表、類型引用對應）
• 資源（圖片、字串表等）

第一步：建立類別庫專案

命令列編譯 (csc.exe)

csc /target:library /out:WebRequest.dll /reference:System.Net.dll WebRequest.cs

• /target:library：產生 DLL 而非 EXE（無需 Main 入口點）。
• /reference (或 /r)：引用相依組件。
• /out：指定輸出檔名。

Visual Studio 操作

1. 建立專案 → 類別庫。
2. 編寫公共類別、介面、列舉等型別。
3. 建置 → 輸出目錄下獲得 .dll。

實戰範例：RequestWebPage 組件

原始碼

using System;
using System.Net;
using System.IO;
using System.Text;

namespace Presenting.CSharp
{
    public class RequestWebPage
    {
        private const int BufferSize = 128;
        private string _url;

        public RequestWebPage() { }
        public RequestWebPage(string url) => _url = url;

        public string Url
        {
            get => _url;
            set => _url = value;
        }

        public void GetContent(out string content)
        {
            if (string.IsNullOrEmpty(_url))
                throw new ArgumentException("URL must be provided.");

            var request = WebRequest.Create(_url);
            using var response = request.GetResponse();
            using var stream = response.GetResponseStream();

            var buffer = new byte[BufferSize];
            var builder = new StringBuilder();
            int bytesRead;
            while ((bytesRead = stream.Read(buffer, 0, BufferSize)) > 0)
            {
                builder.Append(Encoding.ASCII.GetString(buffer, 0, bytesRead));
            }
            content = builder.ToString();
        }
    }
}

設計亮點

• StringBuilder 避免字串重複拷貝，大幅提升大量資料拼接效能。
• using 區塊 確保 WebResponse/Stream 確定性釋放。
• out 參數 明確語意：呼叫端必須接收結果。
• 異常傳播：網路/協議錯誤由呼叫端處理，符合「異常處理原則」。

客戶端使用組件

using System;
using Presenting.CSharp; // 引入命名空間

class TestClient
{
    static void Main()
    {
        var wrq = new RequestWebPage("https://example.com");
        try
        {
            wrq.GetContent(out string html);
            Console.WriteLine(html.Substring(0, Math.Min(500, html.Length)));
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}

編譯客戶端

csc /reference:WebRequest.dll TestClient.cs

命名空間：組織型別的藝術

宣告語法

namespace MyCompany.MyProduct.Module
{
    public class MyClass { }
}

命名慣例

• 範例：Microsoft.AspNetCore.Mvc、Contoso.Payroll.TaxCalculation
• 避免與 .NET 基礎類別庫衝突（勿用 System、Microsoft 開頭）。

跨檔案合併同一命名空間

// File1.cs
namespace Presenting.CSharp { public class WhoisLookup { ... } }

// File2.cs
namespace Presenting.CSharp { public class RequestWebPage { ... } }

編譯單一組件：

csc /target:library /out:Presenting.CSharp.dll /reference:System.Net.dll WhoisLookup.cs RequestWebPage.cs

存取修飾符與可見性

組件邊界是 internal 的終點。設計原則：預設 internal，僅公開必要 API (public)。

私有組件 vs 共用組件

強名稱簽署流程

1. 產生金鑰對：sn -k MyKey.snk
2. 專案屬性 → 簽署 → 勾選「為組件簽署」 → 選擇 .snk。
3. 或命令列：csc /keyfile:MyKey.snl /target:library ...
4. 安裝至 GAC：gacutil /i MyAssembly.dll (需管理員權限)。

版本號語義

• Major：破壞性變更、不相容 API。
• Minor：新增功能、向後相容。
• Build：每日建置編號、修正錯誤。
• Revision：緊急修補、服務包。

組件繫結重導向 (bindingRedirect in app.config) 可解決版本衝突。

現代化建議：.NET Standard / .NET 5+ 類別庫

• 目標框架設為 netstandard2.0 或 net6.0 等，獲得跨平台復用能力。
• 使用 PackageReference 管理 NuGet 相依性，取代 GAC。
• 發布為 NuGet 套件 (dotnet pack)，內建版本管理與相依解析。
• 啟用 Nullable、GenerateDocumentationFile 提升 API 可用性。

總結檢查清單

1. ✅ 專案類型選對 (Class Library)。
2. ✅ 命名空間符合慣例、層次清晰。
3. ✅ 公共 API 僅暴露必要型別/成員 (public)，其餘 internal。
4. ✅ 實作 IDisposable、非同步方法、取消權杖等現代模式。
5. ✅ XML 文件註解 (///) 覆蓋所有公共 API。
6. ✅ 單元測試覆蓋核心邏輯。
7. ✅ 版本號語義化、強名稱 (如需共用) / NuGet 套件化。
8. ✅ 目標框架與相依性最小化 (避免不必要的框架引用)。