ATL COM 伺服器開發入門：從精靈建立到 VB/VC 雙客戶端測試

Active Template Library (ATL) 是開發高效能、輕量級 COM 元件的最佳選擇。本文以循序漸進的方式，引導初學者完成從 ATL 專案建立、COM 物件新增、方法實作、編譯註冊，到 Visual Basic 6.0 與 Visual C++ 控制台應用程式雙重測試的完整流程。

步驟一：啟動 ATL COM AppWizard 建立專案

1. Visual C++ 6.0 → File → New → Projects 標籤 → ATL COM AppWizard
2. 專案名稱：Simple_ATL，路徑：E:\samples\Simple_ATL
3. 精靈設定（關鍵選項）：
   • Server Type：Dynamic Link Library (DLL) — 進程內伺服器
   • 其餘核取方塊保持預設（無屬性、無支援 MFC）
4. Finish → OK 確認專案資訊

步驟二：新增 ATL 簡單物件

1. 切換至 ClassView 標籤
2. 右鍵 Simple_ATL Classes → New ATL Object
3. 選擇 Simple Object → Next
4. ATL Object Wizard Properties 設定：
   • Short Name：First_ATL（其餘自動填入）
   • Attributes 標籤：
     • Threading Model：Apartment（單執行緒單元模型）
     • Interface：Dual（支援 vtable 早期綁定與 IDispatch 晚期綁定）
     • Aggregation：No（不支援聚合）
5. OK 完成物件建立

步驟三：新增自訂方法

1. ClassView 展開 IFirst_ATL 介面節點
2. 右鍵 IFirst_ATL → Add Method
3. 方法設定：
   • Return Type：HRESULT（預設，不可變）
   • Method Name：AddNumbers
   • Parameters：[in] long Num1, [in] long Num2, [out] long *ReturnVal
     • [in]：輸入參數（封送為 by value）
     • [out]：輸出參數（封送為 by reference，需指標）
     • long*：輸出參數必須為指標型別
4. OK 完成，雙擊 AddNumbers 節點編輯實作碼

步驟四：實作方法邏輯

STDMETHODIMP CFirst_ATL::AddNumbers(long Num1, long Num2, long *ReturnVal)
{
    // TODO: Add your implementation code here
    *ReturnVal = Num1 + Num2;
    return S_OK;
}

步驟五：編譯與自動註冊

• 按 F7 編譯專案
• ATL DLL 編譯成功會自動呼叫 DllRegisterServer 完成註冊
• 輸出視窗顯示：「Registering server...」成功訊息

步驟六：Visual Basic 6.0 測試客戶端

1. VB6 → Standard EXE 專案
2. 表單放置一個 CommandButton (Command1)
3. Project → References → 勾選 Simple ATL 1.0 Type Library
4. Command1_Click 事件程式碼：

Private Sub Command1_Click()
    Dim objTestATL As SIMPLE_ATLLib.First_ATL
    Set objTestATL = New First_ATL
    
    Dim lngReturnValue As Long
    objTestATL.AddNumbers 5, 7, lngReturnValue
    
    MsgBox "The value of 5 + 7 is: " & lngReturnValue
    
    Set objTestATL = Nothing
End Sub

步驟七：Visual C++ 控制台應用程式測試

1. 關閉 Simple_ATL 專案，新建 Win32 Console Application：Test_ATL
2. 選擇 "An empty project" → Finish → OK
3. Ctrl+N 新增 C++ Source File：Test_ATL.cpp
4. 完整測試程式碼：

// Test_ATL.cpp
#include 
using namespace std;

// 1. 包含 ATL 產生的標頭檔（需調整路徑）
#include "..\Simple_ATL\Simple_ATL.h"

// 2. 從 Simple_ATL_i.c 複製 GUID 定義（或直接 #include "..\Simple_ATL\Simple_ATL_i.c"）
const IID IID_IFirst_ATL = 
{0xC8F6E230,0x2672,0x11D3,{0xA8,0xA8,0x00,0x10,0x5A,0xA9,0x43,0xDF}};
const CLSID CLSID_First_ATL = 
{0x970599E0,0x2673,0x11D3,{0xA8,0xA8,0x00,0x10,0x5A,0xA9,0x43,0xDF}};

void main(void)
{
    // 3. 宣告介面指標
    HRESULT hr;
    IFirst_ATL *pIFirstATL = NULL;

    // 4. 初始化 COM 程式庫
    hr = CoInitialize(NULL);
    if (FAILED(hr)) return;

    // 5. 建立 COM 物件實例
    hr = CoCreateInstance(
        CLSID_First_ATL, 
        NULL, 
        CLSCTX_INPROC_SERVER, 
        IID_IFirst_ATL, 
        (void**)&pIFirstATL
    );

    if (SUCCEEDED(hr) && pIFirstATL)
    {
        // 6. 呼叫方法（早期綁定，vtable 直接呼叫）
        long ReturnValue;
        pIFirstATL->AddNumbers(5, 7, &ReturnValue);
        cout << "The answer for 5 + 7 is: " << ReturnValue << endl;
        
        // 7. 釋放介面
        pIFirstATL->Release();
    }
    else
    {
        cout << "CoCreateInstance Failed." << endl;
    }

    // 8. 反初始化 COM
    CoUninitialize();
}

關鍵概念總結表

常見問題與解決

• VB 找不到 Type Library：確認 ATL DLL 成功註冊，重啟 VB IDE
• VC 連結錯誤 LNK2001：未包含 Simple_ATL_i.c 或 GUID 定義
• CoCreateInstance 返回 0x80040154：DLL 未註冊，執行 regsvr32 Simple_ATL.dll
• 參數傳遞錯誤：VC 呼叫時輸出參數必須傳址 &ReturnValue

總結

ATL 將繁複的 COM 基礎建設（IUnknown、IClassFactory、註冊表操作、封送處理）封裝為精靈驅動的標準化流程。本文示範的 Simple_ATL 專案從建立到雙客戶端驗證，完整展示了 ATL 開發 COM 進程內伺服器的標準路徑。掌握此流程，即可快速構建高效能、語言中立的可復用元件。