WCF 實戰：使用 Svcutil.exe 生成客戶端代理完整參數指南與 Silverlight 適配技巧

前言

Svcutil.exe (ServiceModel Metadata Utility) 是 WCF 產生客戶端代理類別的核心命令列工具。掌握其關鍵參數，能精確控制同步/非同步方法、集合型別、目標 .NET 版本、資料繫結支援，並解決 Silverlight 專案的特殊相容性問題。

核心參數速查表

常用指令範例

1. 完整功能：非同步 + ObservableCollection + .NET 3.5 + 參考組件

svcutil /a /d:d:/temp https://localhost:1998/Implement/AgriProductService.svc
    /ser:DataContractSerializer /tcv:Version35
    /ct:System.Collections.ObjectModel.ObservableCollection`1
    /reference:"C:/Program Files/Reference Assemblies/Microsoft/Framework/.NETFramework/v4.0/WindowsBase.dll"

2. 非同步 + List<T> 集合

svcutil /a /d:d:/temp https://localhost:1998/Implement/AgriProductService.svc
    /ser:DataContractSerializer /tcv:Version35
    /ct:System.Collections.Generic.List`1

3. 僅非同步 + 陣列集合 (預設)

svcutil /a /d:d:/temp https://localhost:1998/Implement/AgriProductService.svc
    /ser:DataContractSerializer /tcv:Version35

Silverlight 專案適配：三大必做修改

Silverlight 不支援同步呼叫，且預設產生的代理缺少 ChannelBase 實作與 OpenAsync/CloseAsync。須手動調整：

步驟 1：刪除所有同步方法

保留 BeginXxx/EndXxx 與 XxxAsync/XxxCompleted 事件模式。

步驟 2：補充 OpenAsync / CloseAsync 實作

將以下代碼加入產生的 partial class ServiceClient : ClientBase<IService>, IService 中：

// 開啟連線非同步支援
private BeginOperationDelegate onBeginOpenDelegate;
private EndOperationDelegate onEndOpenDelegate;
private SendOrPostCallback onOpenCompletedDelegate;
public event EventHandler<AsyncCompletedEventArgs> OpenCompleted;

private IAsyncResult OnBeginOpen(object[] inValues, AsyncCallback callback, object asyncState)
{
    return ((ICommunicationObject)this).BeginOpen(callback, asyncState);
}
private object[] OnEndOpen(IAsyncResult result)
{
    ((ICommunicationObject)this).EndOpen(result);
    return null;
}
private void OnOpenCompleted(object state)
{
    if (OpenCompleted != null)
    {
        var e = (InvokeAsyncCompletedEventArgs)state;
        OpenCompleted(this, new AsyncCompletedEventArgs(e.Error, e.Cancelled, e.UserState));
    }
}
public void OpenAsync() => OpenAsync(null);
public void OpenAsync(object userState)
{
    onBeginOpenDelegate = onBeginOpenDelegate ?? new BeginOperationDelegate(OnBeginOpen);
    onEndOpenDelegate = onEndOpenDelegate ?? new EndOperationDelegate(OnEndOpen);
    onOpenCompletedDelegate = onOpenCompletedDelegate ?? new SendOrPostCallback(OnOpenCompleted);
    base.InvokeAsync(onBeginOpenDelegate, null, onEndOpenDelegate, onOpenCompletedDelegate, userState);
}

// 關閉連線非同步支援 (同上模式，略)

步驟 3：確保實作 ChannelBase 與 CreateChannel

VS 「加入服務參考」產生的代理已包含此邏輯；Svcutil 產生的版本可能缺失，需手動補齊或改用 VS 介面產生。

已知差異與避坑指南

建議工作流程

1. 開發期：使用 VS 「加入服務參考」獲得完整設計時支援與 IntelliSense。
2. 建置伺服器 / CI/CD：使用 Svcutil.exe 腳本化產生，確保版本一致、可控制參數。
3. Silverlight 專案：VS 產生後手動刪除同步方法、補充 Open/Close Async，或直接使用 SlSvcUtil.exe (Silverlight 專用版本)。

本文出自「突破中的IT架構師」博客：https://virusswb.blog.51cto.com/115214/891014