Общие сведения о клиенте WCF

2025-06-17

В этом разделе описываются действия клиентских приложений, настройка, создание и использование клиента Windows Communication Foundation (WCF) и защита клиентских приложений.

Использование клиентских объектов WCF

Клиентское приложение — это управляемое приложение, которое использует клиент WCF для взаимодействия с другим приложением. Для создания клиентского приложения для службы WCF необходимо выполнить следующие действия.

Получите контракт службы, привязки и сведения об адресе для конечной точки службы.
Создайте клиент WCF с помощью этой информации.
Операции вызова.
Закройте клиентский объект WCF.

В следующих разделах рассматриваются следующие действия и приведены краткие сведения о следующих проблемах:

Обработка ошибок.
Настройка и защита клиентов.
Создание объектов обратного вызова для дуплексных служб.
Асинхронный вызов служб.
Вызов служб с помощью клиентских каналов.

Получение контракта службы, привязок и адресов

В WCF службы и клиенты моделируют контракты, используя управляемые атрибуты, интерфейсы и методы. Чтобы подключиться к службе в клиентском приложении, необходимо получить сведения о типе контракта службы. Как правило, вы получаете сведения о типе контракта службы с помощью средства служебной программы метаданных ServiceModel (Svcutil.exe). Программа загружает метаданные из службы, преобразует его в файл управляемого исходного кода на выбранном языке и создает файл конфигурации клиентского приложения, который можно использовать для настройки клиентского объекта 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 преобразует вызовы метода в сообщения, отправляет их в службу, прослушивает ответ и возвращает эти значения объекту клиента 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, необходимо настроить клиентский объект. В частности, он должен использовать конечную точку службы. Конечная точка — это сочетание контракта службы, привязки и адреса. (Дополнительные сведения о конечных точках см. в разделах "Конечные точки": "Адреса", "Привязки" и "Контракты".) Как правило, эти сведения находятся в <элементе конечной точки> в файле конфигурации клиентского приложения, например в том, который создает средство 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 исключения в дополнение к любым System.ServiceModel.FaultException объектам, вызываемым в результате сбоев SOAP, возвращаемых операциями. Ошибки SOAP, указанные в контракте операции, вызываются клиентским приложениям в качестве System.ServiceModel.FaultException<TDetail> параметра типа— это тип сведений об ошибке SOAP. Дополнительные сведения об обработке ошибок в клиентском приложении см. в разделе "Отправка и получение сбоев". Полный пример показывает, как обрабатывать ошибки в клиенте, см. в разделе "Ожидаемые исключения".

Настройка и защита клиентов

Настройка клиента начинается с требуемой загрузки сведений о конечной точке целевой точки для объекта клиента или канала, как правило, из файла конфигурации, хотя эти сведения также можно загрузить программным способом с помощью конструкторов и свойств клиента. Однако для обеспечения определенного поведения клиента и для многих сценариев безопасности требуются дополнительные действия по настройке.

Например, требования безопасности для контрактов служб объявляются в интерфейсе контракта службы, и если Svcutil.exe создали файл конфигурации, этот файл обычно содержит привязку, которая может поддерживать требования к безопасности службы. Однако в некоторых случаях может потребоваться дополнительная конфигурация безопасности, например настройка учетных данных клиента. Полные сведения о настройке безопасности для клиентов WCF см. в разделе "Защита клиентов".

Кроме того, некоторые пользовательские настройки можно активировать в клиентских приложениях, например, поведение во время выполнения. Дополнительные сведения о настройке пользовательского поведения клиента см. в разделе "Настройка поведения клиента".

Создание объектов обратного вызова для дуплексных служб

Дуплексные службы определяют контракт обратного вызова, который клиентское приложение должно реализовать, чтобы предоставить службе объект, вызываемый в соответствии с требованиями контракта. Хотя объекты обратного вызова не являются полными службами (например, вы не можете инициировать канал с объектом обратного вызова), для целей реализации и настройки их можно рассматривать как вид службы.

Клиенты дуплексных услуг должны:

Реализуйте класс контракта обратного вызова.
Создайте экземпляр класса реализации контракта обратного вызова и используйте его, чтобы создать объект System.ServiceModel.InstanceContext, который вы передаете конструктору клиента WCF.
Вызов операций и обработка обратных вызовов операций.

Дуплексные клиентские объекты WCF работают аналогично своим неудуплексным аналогам, за исключением того, что они обеспечивают функциональность, необходимую для поддержки обратных вызовов, включая настройку службы обратного вызова.

Например, можно управлять различными аспектами поведения среды выполнения объекта обратного вызова с помощью свойств атрибута System.ServiceModel.CallbackBehaviorAttribute класса обратного вызова. Другим примером является использование класса System.ServiceModel.Description.CallbackDebugBehavior для включения возможности возврата сведений об исключении в службы, которые вызывают объект обратного вызова. Дополнительные сведения см. в разделе "Дуплексные службы". Полный пример см. в разделе Дуплекс.

На компьютерах под управлением Windows XP с установленным Internet Information Services (IIS) 5.1 дуплексные клиенты должны указать базовый адрес клиента с помощью класса 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".