C# 組件開發實戰：從建立類別庫到命名空間組織、版本控制與部署策略

什麼是 .NET 組件？

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

• MSIL 代碼（中介語言）
• 型別中繼資料
• 組件資訊清單（名稱、版本、文化特性、強式名稱、檔案清單、型別參考對應）
• 資源（圖片、字串表等）

實戰：建立第一個組件

步驟 1：建立類別庫專案

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

// Visual Studio：新增專案 > 類別庫 (.NET Framework / .NET Core / .NET Standard)

步驟 2：實作核心類別

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

namespace WebUtilities
{
    /// 

    /// 網頁內容擷取元件
    /// 
    public class WebPageRequester
    {
        private const int BufferSize = 4096;
        private string _url;

        public WebPageRequester() { }

        public WebPageRequester(string url) => Url = url;

        public string Url
        {
            get => _url;
            set => _url = value ?? throw new ArgumentNullException(nameof(value));
        }

        /// 

        /// 同步取得網頁內容
        /// 
        /// 輸出 HTML 字串
        /// 成功 true，失敗 false
        /// URL 未設定
        public bool GetContent(out string content)
        {
            content = string.Empty;
            if (string.IsNullOrEmpty(_url))
                throw new ArgumentException("URL 必須指定", nameof(Url));

            try
            {
                var request = WebRequest.Create(_url);
                using var response = request.GetResponse();
                using var stream = response.GetResponseStream();
                using var reader = new StreamReader(stream, Encoding.UTF8);
                
                // 使用 StringBuilder 避免字串連接效能問題
                var sb = new StringBuilder();
                char[] buffer = new char[BufferSize];
                int read;
                while ((read = reader.Read(buffer, 0, BufferSize)) > 0)
                {
                    sb.Append(buffer, 0, read);
                }
                content = sb.ToString();
                return true;
            }
            catch (WebException)
            {
                return false;
            }
        }
    }
}

步驟 3：建置組件

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

步驟 4：建立客戶端應用程式測試

// Client.cs
using System;
using WebUtilities; // 匯入組件命名空間

class Program
{
    static void Main()
    {
        var requester = new WebPageRequester("https://www.example.com");
        
        try
        {
            if (requester.GetContent(out string html))
            {
                Console.WriteLine($"成功取得內容，長度: {html.Length} 字元");
                Console.WriteLine(html.Substring(0, Math.Min(200, html.Length)));
            }
            else
            {
                Console.WriteLine("取得內容失敗");
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"發生錯誤: {ex.Message}");
        }
    }
}

// 編譯客戶端（需參考組件）
csc /reference:WebUtilities.dll Client.cs

命名空間：組織型別的邏輯邊界

宣告與巢狀結構

namespace MyCompany.Products.WebUtilities
{
    // 此處所有型別屬於 MyCompany.Products.WebUtilities
    public class WebPageRequester { ... }
    
    namespace Http
    {
        public class HttpClientWrapper { ... }
    }
}

// 使用：完整名稱或 using 指示詞
var requester = new MyCompany.Products.WebUtilities.WebPageRequester();
// 或
using MyCompany.Products.WebUtilities;
var requester = new WebPageRequester();

命名空間設計原則

• 公司.產品.功能.子系統（如 `Microsoft.AspNetCore.Mvc`）
• 避免與 .NET 基礎類別庫衝突（勿用 `System`、`Microsoft` 開頭）
• 公用 API 必須在命名空間內，避免全域命名空間汙染
• 單一組件可包含多個命名空間；單一命名空間可跨多個組件

存取修飾詞與組件可見性

進階：多類別、多檔案、單一組件

// File: WebPageRequester.cs
namespace WebUtilities { public class WebPageRequester { ... } }

// File: FtpClient.cs
namespace WebUtilities { public class FtpClient { ... } }

// File: NetworkDiagnostics.cs
namespace WebUtilities { public static class NetworkDiagnostics { ... } }

// 一次編譯多檔案產出單一 DLL
csc /target:library /reference:System.Net.dll /out:WebUtilities.dll *.cs

組件版本控制與強式名稱

版本號結構

[Major].[Minor].[Build].[Revision]（如 `2.5.1004.0`）

• Major：重大變更、不相容
• Minor：新增功能、向後相容
• Build：每日建置編號、CI 流水號
• Revision：熱修補、服務包

AssemblyInfo.cs 關鍵屬性

[assembly: AssemblyTitle("WebUtilities")]
[assembly: AssemblyDescription("網路工具元件庫")]
[assembly: AssemblyCompany("MyCompany")]
[assembly: AssemblyProduct("WebUtilities")]
[assembly: AssemblyCopyright("Copyright © 2024")]
[assembly: AssemblyVersion("2.5.*")]        // 自動產生 Build/Revision
[assembly: AssemblyFileVersion("2.5.1004.0")] // 顯示在檔案屬性
[assembly: AssemblyInformationalVersion("2.5.0-beta.1")] // NuGet 套件版本

強式名稱簽署

1. 產生金鑰組：sn -k MyKey.snk
2. 專案屬性 → 簽署 → 勾選「為組件簽署」 → 選取 `.snk`
3. 或命令列：csc /keyfile:MyKey.snk /target:library ...

強式名稱提供：全域唯一身分、防偽造、GAC 部署、版本繫結重導向

部署策略

私有組件

• 放置於應用程式目錄（`bin\Debug`、發布資料夾）
• 無需註冊、無版本衝突（各應用程式獨立副本）
• 最簡單、最常用

共用組件（GAC）

// 安裝至全域組件快取
gacutil /i WebUtilities.dll

// 列出 GAC 組件
gacutil /l WebUtilities

// 移除
gacutil /u WebUtilities

• 需強式名稱
• 多應用程式共用、節省磁碟空間
• 版本並存（GAC 支援同名不同版本）
• .NET Core / .NET 5+ 不再使用 GAC，改用 NuGet 套件管理

NuGet 套件發布

// 建立 .nuspec 或使用 SDK 風格專案檔

  
    netstandard2.0
    MyCompany.WebUtilities
    2.5.0
    MyCompany
    網路工具元件庫
    MIT
  


// 打包
dotnet pack -c Release

// 發布至 nuget.org
dotnet nuget push bin\Release\MyCompany.WebUtilities.2.5.0.nupkg -k YOUR_API_KEY -s https://api.nuget.org/v3/index.json

組件解析與載入機制

執行期依序探測：

1. 應用程式基底目錄
2. 私有路徑（`` 在 app.config）
3. GAC（僅 .NET Framework）
4. AssemblyResolve 事件自訂解析

// 自訂組件解析（插件架構常用）
AppDomain.CurrentDomain.AssemblyResolve += (sender, args) =>
{
    string assemblyName = new AssemblyName(args.Name).Name + ".dll";
    string pluginPath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Plugins", assemblyName);
    return File.Exists(pluginPath) ? Assembly.LoadFrom(pluginPath) : null;
};

總結

C# 組件開發核心流程：類別庫專案 → 命名空間組織 → public API 設計 → 建置 DLL → 版本屬性 → 強式名稱（可選） → 部署策略選擇。掌握命名空間設計、存取修飾詞、版本語意、強式名稱與現代 NuGet 發布流程，即能構建企業級、可重用、可維護的元件生態系統。