WCF 用戶端總覽

本節說明用戶端應用程式的用途、如何設定、建立和使用 Windows Communication Foundation (WCF) 用戶端,以及如何保護用戶端應用程式。

使用 WCF 用戶端物件

用戶端應用程式是一個受控應用程式,它會使用 WCF 用戶端與另一個應用程式進行通訊。 建立 WCF 服務的用戶端應用程式需要執行下列步驟:

  1. 取得服務端點的服務合約、繫結和位址資訊。

  2. 使用該資訊建立 WCF 用戶端。

  3. 呼叫作業。

  4. 關閉 WCF 用戶端物件。

下列各節將討論這些步驟,並簡要介紹以下問題:

  • 處理錯誤。

  • 設定和保護用戶端。

  • 建立雙工服務的回呼物件。

  • 非同步呼叫服務。

  • 透過用戶端通道呼叫服務。

取得服務合約、繫結和位址

在 WCF 中,服務和用戶端會使用 managed 屬性、介面和方法來模型合約。 若要在用戶端應用程式中連接到服務,您必須取得服務合約的類型資訊。 一般來說,您可以使用 [System.servicemodel 中繼資料公用程式] 工具 (Svcutil.exe) 來取得服務合約的類型資訊。 此公用程式會從服務下載中繼資料,並以您選擇的語言將其轉換為 managed 原始程式碼檔,並建立可用來設定 WCF 用戶端物件的用戶端應用程式設定檔。 例如,如果您要建立 WCF 用戶端物件來叫用 MyCalculatorService ,並且知道該服務的中繼資料是在上發行的 http://computerName/MyCalculatorService/Service.svc?wsdl ,則下列程式碼範例會示範如何使用 Svcutil.exe 取得 ClientCode.vb 在 managed 程式碼中包含服務合約的檔案。

svcutil /language:vb /out:ClientCode.vb /config:app.config http://computerName/MyCalculatorService/Service.svc?wsdl  

您可以將此合約程式碼編譯成用戶端應用程式,或編譯成另一個元件,讓用戶端應用程式可以用來建立 WCF 用戶端物件。 您可以使用組態檔來設定用戶端物件,以便正確連接到服務。

如需此程式的範例,請參閱 如何:建立用戶端。 如需有關合約的完整資訊,請參閱 合約

建立 WCF 用戶端物件

WCF 用戶端是一個本機物件,其以用戶端可用來與遠端服務通訊的形式來表示 WCF 服務。 WCF 用戶端類型會執行目標服務合約,所以當您建立並設定它時,您就可以直接使用用戶端物件來叫用服務作業。 WCF 執行時間會將方法呼叫轉換為訊息、將其傳送至服務、接聽回復,然後將這些值傳回至 WCF 用戶端物件,做為傳回值或 outref 參數。

您也可以使用 WCF 用戶端通道物件來連接及使用服務。 如需詳細資訊,請參閱 WCF 用戶端架構

建立新的 WCF 物件

為說明 ClientBase<TChannel> 類別的使用方式,請假設已從服務應用程式產生下列簡單服務合約。

注意

如果您使用 Visual Studio 建立 WCF 用戶端,當您將服務參考加入至專案時,物件會自動載入至物件瀏覽器。

[System.ServiceModel.ServiceContractAttribute(
  Namespace = "http://microsoft.wcf.documentation"
)]
public interface ISampleService
{
    [System.ServiceModel.OperationContractAttribute(
      Action = "http://microsoft.wcf.documentation/ISampleService/SampleMethod",
      ReplyAction = "http://microsoft.wcf.documentation/ISampleService/SampleMethodResponse"
    )]
    [System.ServiceModel.FaultContractAttribute(
      typeof(microsoft.wcf.documentation.SampleFault),
      Action = "http://microsoft.wcf.documentation/ISampleService/SampleMethodSampleFaultFault"
    )]
    string SampleMethod(string msg);
}

如果您不是使用 Visual Studio,請檢查產生的合約程式碼,以找出延伸的型別 ClientBase<TChannel> 和服務合約介面 ISampleService 。 在這種情況下,該型別看起來類似下列程式碼:

[System.CodeDom.Compiler.GeneratedCodeAttribute("System.ServiceModel", "3.0.0.0")]
public partial class SampleServiceClient : System.ServiceModel.ClientBase<ISampleService>, ISampleService
{

    public SampleServiceClient()
    {
    }

    public SampleServiceClient(string endpointConfigurationName)
        :
            base(endpointConfigurationName)
    {
    }

    public SampleServiceClient(string endpointConfigurationName, string remoteAddress)
        :
            base(endpointConfigurationName, remoteAddress)
    {
    }

    public SampleServiceClient(string endpointConfigurationName, System.ServiceModel.EndpointAddress remoteAddress)
        :
            base(endpointConfigurationName, remoteAddress)
    {
    }

    public SampleServiceClient(System.ServiceModel.Channels.Binding binding, System.ServiceModel.EndpointAddress remoteAddress)
        :
            base(binding, remoteAddress)
    {
    }
    public string SampleMethod(string msg)
    {
        return base.Channel.SampleMethod(msg);
    }
}

您可以將這個類別建立成本機物件,其方式是使用其中一個建構函式,然後加以設定,再用來連接到型別為 ISampleService 的服務。

建議您先建立 WCF 用戶端物件,然後在單一 try/catch 區塊內使用並關閉它。 請勿 using Using 在 Visual Basic) 中使用語句 (,因為它可以遮罩特定失敗模式的例外狀況。 如需詳細資訊,請參閱下列各節,以及 使用 Close 和 Abort 釋放 WCF 用戶端資源

合約、繫結和位址

您必須先設定用戶端物件,才可以建立 WCF 用戶端物件。 具體而言,它必須有要使用的服務 端點 。 端點是服務合約、繫結和位址的組合 (如需端點的詳細資訊,請參閱 端點:位址、系結和合約) 。這項資訊通常位於 <endpoint> 用戶端應用程式設定檔中的元素中,例如 Svcutil.exe 工具產生的專案,以及在您建立用戶端物件時自動載入的專案。 這兩種 WCF 用戶端類型也有多載,可讓您以程式設計方式指定這項資訊。

例如,針對前面範例中使用的 ISampleService 所產生的組態檔會包含下列端點資訊。

<configuration>
    <system.serviceModel>
        <bindings>
            <wsHttpBinding>
                <binding name="WSHttpBinding_ISampleService" closeTimeout="00:01:00"
                    openTimeout="00:01:00" receiveTimeout="00:01:00" sendTimeout="00:01:00"
                    bypassProxyOnLocal="false" transactionFlow="false" hostNameComparisonMode="StrongWildcard"
                    maxBufferPoolSize="524288" maxReceivedMessageSize="65536"
                    messageEncoding="Text" textEncoding="utf-8" useDefaultWebProxy="true"
                    allowCookies="false">
                    <readerQuotas maxDepth="32" maxStringContentLength="8192" maxArrayLength="16384"
                        maxBytesPerRead="4096" maxNameTableCharCount="16384" />
                    <reliableSession ordered="true" inactivityTimeout="00:10:00"
                        enabled="false" />
                    <security mode="Message">
                        <transport clientCredentialType="None" proxyCredentialType="None"
                            realm="" />
                        <message clientCredentialType="Windows" negotiateServiceCredential="true"
                            algorithmSuite="Default" establishSecurityContext="true" />
                    </security>
                </binding>
            </wsHttpBinding>
        </bindings>
        <client>
            <endpoint address="http://localhost:8080/SampleService" binding="wsHttpBinding"
                bindingConfiguration="WSHttpBinding_ISampleService" contract="ISampleService"
                name="WSHttpBinding_ISampleService">
            </endpoint>
        </client>
    </system.serviceModel>
</configuration>

這個組態檔會在 <client> 元素中指定目標端點。 如需使用多個目標端點的詳細資訊,請參閱或函式 ClientBase<TChannel> ChannelFactory<TChannel>

呼叫作業

當您建立並設定用戶端物件之後,請建立 try/catch 區塊,並以您在本機物件時所使用的相同方式來呼叫作業,並關閉 WCF 用戶端物件。 當用戶端應用程式呼叫第一項作業時,WCF 會自動開啟基礎通道,而當物件被回收時,就會關閉基礎通道。 (或者,您也可以在呼叫其他作業之前或之後明確地開啟和關閉通道)。

例如,您若有下列服務合約:

namespace Microsoft.ServiceModel.Samples  
{  
    using System;  
    using System.ServiceModel;  
  
    [ServiceContract(Namespace = "http://Microsoft.ServiceModel.Samples")]  
    public interface ICalculator  
   {  
        [OperationContract]  
        double Add(double n1, double n2);  
        [OperationContract]  
        double Subtract(double n1, double n2);  
        [OperationContract]  
        double Multiply(double n1, double n2);  
        [OperationContract]  
        double Divide(double n1, double n2);  
    }  
}  
Namespace Microsoft.ServiceModel.Samples  
  
    Imports System  
    Imports System.ServiceModel  
  
    <ServiceContract(Namespace:= _  
    "http://Microsoft.ServiceModel.Samples")> _
   Public Interface ICalculator  
        <OperationContract> _
        Function Add(n1 As Double, n2 As Double) As Double  
        <OperationContract> _
        Function Subtract(n1 As Double, n2 As Double) As Double  
        <OperationContract> _
        Function Multiply(n1 As Double, n2 As Double) As Double  
        <OperationContract> _
     Function Divide(n1 As Double, n2 As Double) As Double  
End Interface  

您可以藉由建立 WCF 用戶端物件並呼叫其方法來呼叫作業,如下列程式碼範例所示。 WCF 用戶端物件的開啟、呼叫和關閉會在單一 try/catch 區塊中進行。 如需詳細資訊,請參閱 使用 Wcf 用戶端存取服務使用 Close 和 Abort 釋放 WCF 用戶端資源

CalculatorClient wcfClient = new CalculatorClient();
try
{
    Console.WriteLine(wcfClient.Add(4, 6));
    wcfClient.Close();
}
catch (TimeoutException timeout)
{
    // Handle the timeout exception.
    wcfClient.Abort();
}
catch (CommunicationException commException)
{
    // Handle the communication exception.
    wcfClient.Abort();
}

處理錯誤

當開啟基礎用戶端通道 (無論是明確或是自動呼叫作業)、使用用戶端或通道物件來呼叫作業,或關閉基礎用戶端通道時,都可能會在用戶端應用程式中發生例外狀況。 除了要由作業傳回因 SOAP 錯誤而擲回的任何 System.TimeoutException 物件之外,建議您最少還要讓應用程式有能力處理可能發生的 System.ServiceModel.CommunicationExceptionSystem.ServiceModel.FaultException 例外狀況。 作業合約中指定的 SOAP 錯誤會針對用戶端應用程式引發為 System.ServiceModel.FaultException<TDetail>,其中的型別參數是 SOAP 錯誤的詳細類型。 如需在用戶端應用程式中處理錯誤狀況的詳細資訊,請參閱傳送 和接收錯誤。 如需示範如何在用戶端中處理錯誤的完整範例,請參閱 預期的例外狀況。

設定和保護用戶端

設定用戶端時,通常是先從組態檔載入用戶端或通道物件的必要目標端點資訊;儘管可以透過用戶端建構函式和屬性,使用程式設計方式載入這項資訊, 但是為了啟用特定用戶端行為,並符合許多安全性案例的需要,您應該另外執行其他必要的設定步驟。

例如,服務合約的安全性需求會在服務合約介面中宣告;如果 Svcutil.exe 建立了組態檔,這個檔案通常應包含能夠支援服務安全性需求的繫結。 不過,在某些情況下,可能需要進行更多的安全性設定,例如設定用戶端認證。 如需 WCF 用戶端安全性設定的完整資訊,請參閱 保護用戶端

此外,還可以在用戶端應用程式中啟用某些自訂修改,例如自訂執行階段行為。 如需有關如何設定自訂用戶端行為的詳細資訊,請參閱設定 用戶端行為。

建立雙工服務的回呼物件

雙工服務會指定回呼合約,這是用戶端應用程式為了在服務根據合約需求進行呼叫時提供其所需之回呼物件而必須實作的合約。 雖然回呼物件並非完整的服務 (例如,您無法透過回呼物件啟始通道),但基於實作和組態設定的目的,不妨將它們視為一種服務。

雙工服務的用戶端必須:

  • 實作回呼合約類別。

  • 建立回呼合約實類別的實例,並使用它來建立 System.ServiceModel.InstanceContext 您傳遞至 WCF 用戶端函式的物件。

  • 叫用作業和處理作業回呼。

雙工 WCF 用戶端物件的運作方式類似其非雙工的對應專案,唯一的例外是它們會公開支援回呼所需的功能,包括回呼服務的設定。

例如,您可以在回呼類別上使用 System.ServiceModel.CallbackBehaviorAttribute 屬性 (Attribute) 的屬性 (Property),控制回呼物件執行階段行為的各種層面。 此外,還可以使用 System.ServiceModel.Description.CallbackDebugBehavior 類別,讓例外狀況資訊回傳給呼叫回呼物件的服務。 如需詳細資訊,請參閱 雙工服務。 如需完整範例,請參閱 雙工

在執行 Internet Information Services (IIS) 5.1 的 Windows XP 電腦上,雙工用戶端必須使用 System.ServiceModel.WSDualHttpBinding 類別來指定用戶端基底位址,否則會擲回例外狀況。 下列程式碼範例示範如何在程式碼中執行這項工作。

WSDualHttpBinding dualBinding = new WSDualHttpBinding();
EndpointAddress endptadr = new EndpointAddress("http://localhost:12000/DuplexTestUsingCode/Server");
dualBinding.ClientBaseAddress = new Uri("http://localhost:8000/DuplexTestUsingCode/Client/");

Dim dualBinding As New WSDualHttpBinding()
Dim endptadr As New EndpointAddress("http://localhost:12000/DuplexTestUsingCode/Server")
dualBinding.ClientBaseAddress = New Uri("http://localhost:8000/DuplexTestUsingCode/Client/")

下列程式碼範例示範如何在組態檔中執行這項工作。

<client>
  <endpoint
    name ="ServerEndpoint"
    address="http://localhost:12000/DuplexUsingConfig/Server"
    bindingConfiguration="WSDualHttpBinding_IDuplex"
    binding="wsDualHttpBinding"
    contract="IDuplex"
/>
</client>
<bindings>
  <wsDualHttpBinding>
    <binding
      name="WSDualHttpBinding_IDuplex"
      clientBaseAddress="http://localhost:8000/myClient/"
    />
  </wsDualHttpBinding>
</bindings>

以非同步方式呼叫服務

呼叫作業的方式完全取決於用戶端開發人員。 這是因為透過 Managed 程式碼來表達呼叫程序時,您可以將組成作業的訊息對應至同步或非同步的方法。 因此,如果要建置以非同步方式呼叫作業的用戶端,您可以透過 Svcutil.exe,使用 /async 選項來產生非同步用戶端程式碼。 如需詳細資訊,請參閱 如何:以非同步方式呼叫服務作業

使用 WCF 用戶端通道呼叫服務

WCF 用戶端型別會擴充 ClientBase<TChannel> ,而這本身會衍生自 System.ServiceModel.IClientChannel 介面,以公開基礎通道系統。 您可以搭配 System.ServiceModel.ChannelFactory<TChannel> 類別使用目標服務合約來叫用服務。 如需詳細資訊,請參閱 WCF 用戶端架構

另請參閱