共用方式為

WCF 用戶端概觀

本節說明用戶端應用程式的用途、如何設定、建立和使用 Windows Communication Foundation （WCF） 用戶端，以及如何保護用戶端應用程式的安全。

使用 WCF 客戶端物件

用戶端應用程式是使用 WCF 用戶端與其他應用程式通訊的受控應用程式。 建立 WCF 服務的用戶端應用程式需要下列步驟：

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

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

  3. 呼叫作業。

  4. 關閉 WCF 客戶端物件。

下列各節將討論這些步驟，並提供下列問題的簡短簡介：

  • 處理錯誤。

  • 設定和保護用戶端。

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

  • 以異步方式呼叫服務。

  • 使用用戶端通道呼叫服務。

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

在 WCF 中，服務和用戶端會使用 Managed 屬性、介面和方法建立合約模型。 若要連線到用戶端應用程式中的服務，您必須取得服務合約的類型資訊。 一般而言，您可以使用 ServiceModel 元數據公用程式工具 （Svcutil.exe）取得服務合約的類型資訊。 公用程式會從服務下載元數據、使用您選擇的語言將它轉換成 Managed 原始碼檔案，並建立可用來設定 WCF 用戶端物件的用戶端應用程式組態檔。 例如，如果您要建立 WCF 用戶端物件來調用 MyCalculatorService，並且您知道該服務的元數據發佈在 http://computerName/MyCalculatorService/Service.svc?wsdl，則下例程式碼示範如何使用 Svcutil.exe 來取得一個在受控代碼中包含服務合約的 ClientCode.vb 檔案。

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

您可以將此合約程式代碼編譯成用戶端應用程式，也可以編譯成用戶端應用程式接著可用來建立 WCF 用戶端物件的另一個組件。 您可以使用群組態檔來設定客戶端物件，以正確連線到服務 。

如需此程式的範例，請參閱 如何：建立用戶端。 如需合約的詳細資訊，請參閱 合約。

建立 WCF 客戶端物件

WCF 用戶端是一個本機物件，用於表示用戶端可以與遠端服務進行通訊的 WCF 服務。 WCF 用戶端類型會實作目標服務合約，因此當您建立一個並加以設定時，您就可以直接使用客戶端物件來叫用服務作業。 WCF 執行時會將方法呼叫轉換成訊息，發送給服務，監聽回覆，並將這些值以回傳值或outref參數的形式回傳給 WCF 用戶端物件。

您也可以使用 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 客戶端物件。 具體來說，它必須有要使用的服務 端點 。 端點是服務合約、系結和地址的組合。 （如需端點的詳細資訊，請參閱 端點：位址、系結和合約。）一般而言，這項資訊位於 <用戶端應用程式組態檔中的端點元素中，例如 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();
}

處理錯誤

開啟基礎用戶端通道（無論是明確或自動呼叫作業）、使用用戶端或通道物件呼叫作業，或關閉基礎用戶端通道時，用戶端應用程式可能會發生例外狀況。 建議應用程式至少預期要處理可能的System.TimeoutException和System.ServiceModel.CommunicationException例外狀況，並且還要應付作業傳回的 SOAP 錯誤所擲回的任何System.ServiceModel.FaultException物件。 作業合約中指定的 SOAP 錯誤會作為System.ServiceModel.FaultException<TDetail>拋出至用戶端應用程式，其中的 type 參數是 SOAP 錯誤的詳細類型。 如需在用戶端應用程式中處理錯誤狀況的詳細資訊，請參閱 傳送和接收錯誤。 如需完整的範例，示範如何處理用戶端中的錯誤，請參閱 預期的例外狀況。

設定和保護用戶端

設定用戶端會從用戶端或通道物件所需的目標端點資訊載入開始，通常是從組態檔載入，不過您也可以使用用戶端建構函式和屬性以程序設計方式載入此資訊。 不過，需要額外的設定步驟，才能啟用特定客戶端行為，以及針對許多安全性案例。

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

此外，客戶端應用程式中還能啟用一些自訂修改，例如自訂執行時行為。 如需如何設定自定義客戶端行為的詳細資訊，請參閱 設定客戶端行為。

建立雙工服務的回調物件

雙工服務會指定用戶端應用程式必須實作的回呼契約，以便根據契約的需求，提供回呼物件供服務呼叫。 雖然回呼物件不是完整的服務（例如，您無法使用回呼物件起始通道），但為了實作和設定，它們可以視為一種服務。

雙工服務的客戶必須：

  • 實作回調合約類別。

  • 建立回呼合約實作類別的一個實例，並使用該實例來建立您傳遞至 WCF 用戶端構造函數的 System.ServiceModel.InstanceContext 物件。

  • 叫用作業並處理作業回調。

雙工 WCF 用戶端物件的運作方式與非雙工對應項目相似，但不同之處在於它們公開支援回呼所需的功能，包括回呼服務的設定。

例如，您可以使用回呼類別上 System.ServiceModel.CallbackBehaviorAttribute 屬性的屬性來控制回呼物件執行階段行為的各個層面。 另一個範例是 使用 System.ServiceModel.Description.CallbackDebugBehavior 類別，將例外狀況資訊傳回給呼叫回呼對象的服務。 如需詳細資訊，請參閱 雙工服務。 如需完整的範例，請參閱 Duplex。

在執行 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>

以異步方式呼叫服務

呼叫作業的方式完全由客戶端開發人員決定。 在受管理的程式碼中表示時，作業所組成的訊息可以對應到同步或非同步的方法。 因此，如果您想要以異步方式建置呼叫作業的用戶端，您可以使用 Svcutil.exe 來使用 /async 選項產生異步客戶端程序代碼。 如需詳細資訊，請參閱 如何：以異步方式呼叫服務作業。

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

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

另請參閱

  • Last updated on