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

Статья
04/07/2023

В этом разделе описываются действия клиентских приложений, настройка, создание и использование клиента 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. Дополнительные сведения см. в разделе Accessing Services Using a WCF Client and Use Close and Abort to release to release WCF client resources.

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 с запущенными службами 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".