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

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

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

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

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

  2. Создайте клиент WCF, используя эти сведения.

  3. Вызовите операции.

  4. Закройте клиентский объект 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 в качестве возвращаемых значений или out ref параметров.

Вы также можете использовать объекты канала клиента 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), так как он может маскировать исключения в определенных режимах сбоя. Дополнительные сведения см. в следующих разделах, а также Использование закрытия и прерывания для освобождения ресурсов клиента 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();
}

Обработка ошибок

Исключения могут возникать в клиентском приложении при открытии базового клиентского канала (как явно, так и автоматически путем вызова операции) с использованием клиента или объекта канала для вызова операций или при закрытии базового клиентского канала. Рекомендуется, чтобы приложения по крайней мере обрабатывали возможные исключения 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.

См. также