Общие сведения о клиентах WCFWCF Client Overview

В этом разделе описывается, какие клиентские приложения выполняют, как настроить, создать и использовать клиент Windows Communication Foundation (WCF) и как защитить клиентские приложения.This section describes what client applications do, how to configure, create, and use a Windows Communication Foundation (WCF) client, and how to secure client applications.

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

Клиентское приложение — это управляемое приложение, которое использует клиент WCF для взаимодействия с другим приложением.A client application is a managed application that uses a WCF client to communicate with another application. Чтобы создать клиентское приложение для службы WCF, необходимо выполнить следующие действия.To create a client application for a WCF service requires the following steps:

  1. Получите контракт службы, привязки и адрес для конечной точки службы.Obtain the service contract, bindings, and address information for a service endpoint.

  2. Создайте клиент WCF, используя эти сведения.Create a WCF client using that information.

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

  4. Закройте клиентский объект WCF.Close the WCF client object.

В последующих разделах рассматриваются эти действия и представляется краткое введение в следующие вопросы.The following sections discuss these steps and provide brief introductions to the following issues:

  • Обработка ошибок.Handling errors.

  • Настройка и обеспечение безопасности клиентов.Configuring and securing clients.

  • Создание объектов обратного вызова для дуплексных служб.Creating callback objects for duplex services.

  • Вызов служб асинхронно.Calling services asynchronously.

  • Вызов служб с использованием клиентских каналов.Calling services using client channels.

Получение контракта службы, привязок и адресовObtain the Service Contract, Bindings, and Addresses

В WCF модели и клиенты моделируют контракты с помощью управляемых атрибутов, интерфейсов и методов.In WCF, services and clients model contracts using managed attributes, interfaces, and methods. Чтобы подключиться к службе в клиентском приложении, необходимо получить информацию о типе для контракта службы.To connect to a service in a client application, you need to obtain the type information for the service contract. Как правило, это делается с помощью средства служебной программы метаданных ServiceModel (Svcutil. exe), которое скачивает метаданные из службы, преобразует их в управляемый вами язык и создает файл конфигурации клиентского приложения. , который можно использовать для настройки объекта клиента WCF.Typically, you do this by using the ServiceModel Metadata Utility Tool (Svcutil.exe), which downloads metadata from the service, converts it to a managed source code file in the language of your choice, and creates a client application configuration file that you can use to configure your WCF client object. Например, если вы собираетесь создать клиентский объект WCF для вызова MyCalculatorService, и известно, что метаданные для этой службы опубликованы в http://computerName/MyCalculatorService/Service.svc?wsdl, в следующем примере кода показано, как использовать Svcutil ClientCode.vb . exe для получения файла, содержит контракт службы в управляемом коде.For example, if you are going to create an WCF client object to invoke a MyCalculatorService, and you know that the metadata for that service is published at http://computerName/MyCalculatorService/Service.svc?wsdl, then the following code example shows how to use Svcutil.exe to obtain a ClientCode.vb file that contains the service contract in managed code.

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

Можно либо скомпилировать этот код контракта в клиентское приложение, либо в другую сборку, которую клиентское приложение затем может использовать для создания клиентского объекта WCF.You can either compile this contract code into the client application or into another assembly that the client application can then use to create an WCF client object. Можно использовать файл конфигурации, чтобы настроить объект клиента для правильного подключения к службе.You can use the configuration file to configure the client object to properly connect to the service .

Пример этого процесса см. в разделе как Создайте клиент.For an example of this process, see How to: Create a Client. Более полные сведения о контрактах см. в разделе контракты.For more complete information about contracts, see Contracts.

Создание объекта клиента WCFCreate a WCF Client Object

Клиент WCF — это локальный объект, представляющий службу WCF в форме, которую клиент может использовать для взаимодействия с удаленной службой.A WCF client is a local object that represents a WCF service in a form that the client can use to communicate with the remote service. Типы клиентов WCF реализуют контракт целевой службы, поэтому при его создании и настройке можно использовать объект клиента непосредственно для вызова операций службы.WCF client types implement the target service contract, so when you create one and configure it, you can then use the client object directly to invoke service operations. Время выполнения WCF преобразует вызовы методов в сообщения, отправляет их службе, прослушивает ответ и возвращает эти значения в клиентский объект WCF в качестве возвращаемых значений или out ref параметров.The WCF run time converts the method calls into messages, sends them to the service, listens for the reply, and returns those values to the WCF client object as return values or out or ref parameters.

Вы также можете использовать объекты канала клиента WCF для подключения и использования служб.You can also use WCF client channel objects to connect with and use services. Дополнительные сведения см. в разделе архитектура клиента WCF.For details, see WCF Client Architecture.

Создание нового объекта WCFCreating a New WCF Object

Чтобы продемонстрировать использование класса ClientBase<TChannel>, предположим, что следующий простой контракт службы создан из приложения службы.To illustrate the use of a ClientBase<TChannel> class, assume the following simple service contract has been generated from a service application.

Примечание

Если вы используете Visual Studio для создания клиента WCF, объекты автоматически загружаются в обозреватель объектов при добавлении ссылки на службу в проект.If you are using Visual Studio to create your WCF client, objects are loaded automatically into the object browser when you add a service reference to your project.

[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контракта службы.If you are not using Visual Studio, examine the generated contract code to find the type that extends ClientBase<TChannel> and the service contract interface ISampleService. В этом случае такой тип выглядит как следующий код.In this case, that type looks like the following code:

[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.This class can be created as a local object using one of the constructors, configured, and then used to connect to a service of the type ISampleService.

Рекомендуется сначала создать объект клиента WCF, а затем использовать его и закрыть в рамках одного блока try/catch.It is recommended that you create your WCF client object first, and then use it and close it inside a single try/catch block. Не следует использовать оператор ( using Using в Visual Basic), так как он может маскировать исключения в определенных режимах сбоя.You should not use the using statement (Using in Visual Basic) because it may mask exceptions in certain failure modes. Дополнительные сведения см. в следующих разделах, а также Использование закрытия и прерывания для освобождения ресурсов клиента WCF.For more information, see the following sections as well as Use Close and Abort to release WCF client resources.

Контракты, привязки и адресаContracts, Bindings, and Addresses

Прежде чем можно будет создать клиентский объект WCF, необходимо настроить клиентский объект.Before you can create a WCF client object, you must configure the client object. В частности, она должна иметь конечную точку службы для использования.Specifically, it must have a service endpoint to use. Конечная точка - это комбинация контракта службы, привязки и адреса.An endpoint is the combination of a service contract, a binding, and an address. (Дополнительные сведения о конечных точках см . в разделе конечные точки: Адреса, привязки и контракты.) Как правило, эта информация находится в <элементе Endpoint > в файле конфигурации клиентского приложения, например в том, что создает средство Svcutil. exe и автоматически загружается при создании клиентского объекта.(For more information about endpoints, see Endpoints: Addresses, Bindings, and Contracts.) Typically, this information is located in the <endpoint> element in a client application configuration file, such as the one the Svcutil.exe tool generates, and is loaded automatically when you create your client object. Оба типа клиента WCF также имеют перегрузки, которые позволяют программно задавать эти сведения.Both WCF client types also have overloads that enable you to programmatically specify this information.

Например, созданный файл конфигурации для службы ISampleService, используемый в предыдущих примерах, содержит следующие сведения о конечных точках.For example, a generated configuration file for an ISampleService used in the preceding examples contains the following endpoint information.

<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>.This configuration file specifies a target endpoint in the <client> element. Дополнительные сведения об использовании нескольких целевых конечных точек см. ClientBase<TChannel>.ClientBase<TChannel> в разделе ChannelFactory<TChannel>.ChannelFactory<TChannel> или конструкторах.For more information about using multiple target endpoints, see the ClientBase<TChannel>.ClientBase<TChannel> or the ChannelFactory<TChannel>.ChannelFactory<TChannel> constructors.

Вызов операцийCalling Operations

После создания и настройки клиентского объекта создайте блок try/catch, вызовите операции так же, как если бы объект был локальным, и закройте клиентский объект WCF.Once you have a client object created and configured, create a try/catch block, call operations in the same way that you would if the object were local, and close the WCF client object. Когда клиентское приложение вызывает первую операцию, WCF автоматически открывает базовый канал, а базовый канал закрывается при перезапуске объекта.When the client application calls the first operation, WCF automatically opens the underlying channel, and the underlying channel is closed when the object is recycled. (Также можно явно открыть и закрыть канал до или после вызова других операций.)(Alternatively, you can also explicitly open and close the channel prior to or subsequent to calling other operations.)

Например, в случае следующего контракта службы.For example, if you have the following service contract:

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 и вызвав его методы, как показано в следующем примере кода.You can call operations by creating a WCF client object and calling its methods, as the following code example demonstrates. Обратите внимание, что открытие, вызов и закрытие клиентского объекта WCF происходит в одном блоке try/catch.Note that the opening, calling, and closing of the WCF client object occurs within a single try/catch block. Дополнительные сведения см. в статьях доступ к службам с помощью клиента WCF и Использование функции Close и Abort для освобождения ресурсов клиента WCF.For more information, see Accessing Services Using a WCF Client and Use Close and Abort 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();
}

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

Исключения могут возникать в клиентском приложении при открытии базового клиентского канала (как явно, так и автоматически путем вызова операции) с использованием клиента или объекта канала для вызова операций или при закрытии базового клиентского канала.Exceptions can occur in a client application when opening the underlying client channel (whether explicitly or automatically by calling an operation), using the client or channel object to call operations, or when closing the underlying client channel. Рекомендуется, чтобы приложения по крайней мере обрабатывали возможные исключения System.TimeoutException и System.ServiceModel.CommunicationException помимо любых объектов System.ServiceModel.FaultException, созданных в результате ошибок SOAP, возвращенных операциями.It is recommended at a minimum that applications expect to handle possible System.TimeoutException and System.ServiceModel.CommunicationException exceptions in addition to any System.ServiceModel.FaultException objects thrown as a result of SOAP faults returned by operations. Ошибки протокола SOAP, указанные в контракте операции, распространяются до клиентских приложений в виде исключения System.ServiceModel.FaultException<TDetail>, в котором параметр типа представляет собой тип сведений ошибки SOAP.SOAP faults specified in the operation contract are raised to client applications as a System.ServiceModel.FaultException<TDetail> where the type parameter is the detail type of the SOAP fault. Дополнительные сведения об обработке условий ошибок в клиентском приложении см. в разделе Отправка и получение ошибок.For more information about handling error conditions in a client application, see Sending and Receiving Faults. Полный пример, демонстрирующий обработку ошибок в клиенте, см. в разделе ожидаемые исключения.For a complete sample the shows how to handle errors in a client, see Expected Exceptions.

Настройка и обеспечение безопасности клиентовConfiguring and Securing Clients

Настройка клиента начинается с обязательной загрузки информации о целевых конечных точках для клиента или объекта канала, как правило, из файла конфигурации, хотя эту информацию также можно загрузить программными средствами с использованием конструкторов и свойств клиента.Configuring a client starts with the required loading of target endpoint information for the client or channel object, usually from a configuration file, although you can also load this information programmatically using the client constructors and properties. Однако для включения определенного поведения клиента и для большинства сценариев безопасности требуются дополнительные этапы конфигурации.However, additional configuration steps are required to enable certain client behavior and for many security scenarios.

Например, требования безопасности для контрактов службы объявлены в интерфейсе контрактов службы, и если Svcutil.exe создал файл конфигурации, этот файл обычно содержит привязку, которая может поддерживать требования безопасности службы.For example, security requirements for service contracts are declared in the service contract interface, and if Svcutil.exe created a configuration file, that file usually contains a binding that is capable of supporting the security requirements of the service. Однако в некоторых случаях может потребоваться более точная конфигурация безопасности, например настройка учетных данных клиента.In some cases, however, more security configuration may be required, such as configuring client credentials. Полные сведения о настройке безопасности для клиентов WCF см. в разделе Защита клиентов.For complete information about the configuration of security for WCF clients, see Securing Clients.

Кроме того, можно включить некоторые пользовательские изменения в клиентские приложения, такие как пользовательское поведение во время выполнения.In addition, some custom modifications can be enabled in client applications, such as custom run-time behaviors. Дополнительные сведения о настройке пользовательского поведения клиента см. в разделе Настройка поведения клиента.For more information about how to configure a custom client behavior, see Configuring Client Behaviors.

Создание объектов обратного вызова для дуплексных службCreating Callback Objects for Duplex Services

Дуплексные службы задают контракт обратного вызова, который должно реализовать клиентское приложение, чтобы обеспечить объект обратного вызова для вызываемой службы в соответствии с требованиями контракта.Duplex services specify a callback contract that the client application must implement in order to provide a callback object for the service to call according to the requirements of the contract. Хотя объекты обратного вызова не являются полноценными службами (например, невозможно инициировать канал с объектом обратного вызова), в целях реализации и конфигурации их можно рассматривать как тип службы.Although callback objects are not full services (for example, you cannot initiate a channel with a callback object), for the purposes of implementation and configuration they can be thought of as a kind of service.

Клиенты дуплексных служб должны выполнять следующее.Clients of duplex services must:

  • Реализовывать класс контракта обратного вызова.Implement a callback contract class.

  • Создайте экземпляр класса реализации контракта обратного вызова и используйте его для создания System.ServiceModel.InstanceContext объекта, передаваемого в конструктор клиента WCF.Create an instance of the callback contract implementation class and use it to create the System.ServiceModel.InstanceContext object that you pass to the WCF client constructor.

  • Вызывать операции и обрабатывать обратные вызовы операций.Invoke operations and handle operation callbacks.

Дуплексные клиентские объекты WCF работают как недуплексные аналоги, за исключением того, что они предоставляют функции, необходимые для поддержки обратных вызовов, включая настройку службы обратного вызова.Duplex WCF client objects function like their nonduplex counterparts, with the exception that they expose the functionality necessary to support callbacks, including the configuration of the callback service.

Например, невозможно управлять различными аспектами поведения среды выполнения объекта обратного вызова, используя свойства атрибута System.ServiceModel.CallbackBehaviorAttribute класса обратного вызова.For example, you can control various aspects of callback object runtime behavior by using properties of the System.ServiceModel.CallbackBehaviorAttribute attribute on the callback class. Еще одним примером является использование класса System.ServiceModel.Description.CallbackDebugBehavior для включения возвращения сведений об исключениях в службы, вызывающие объект обратного вызова.Another example is the use of the System.ServiceModel.Description.CallbackDebugBehavior class to enable the return of exception information to services that call the callback object. Дополнительные сведения см. в разделе Дуплексные службы.For more information, see Duplex Services. Полный пример см. в разделе дуплекс.For a complete sample, see Duplex.

На компьютерах под управлением ОС Windows XP с запущенными службами IIS 5.1 дуплексные клиенты должны задавать базовый адрес клиента с помощью класса System.ServiceModel.WSDualHttpBinding, в противном случае возникает исключение.On Windows XP computers running Internet Information Services (IIS) 5.1, duplex clients must specify a client base address using the System.ServiceModel.WSDualHttpBinding class or an exception is thrown. В следующем примере кода показано, как это сделать в коде.The following code example shows how to do this in code.

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/")

В следующем коде показано, как это сделать в файле конфигурации.The following code shows how to do this in a configuration file

<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>

Вызов служб асинхронноCalling Services Asynchronously

Способ вызова операций полностью зависит от разработчика клиента.How operations are called is entirely up to the client developer. Это объясняется тем, что сообщения, составляющие операцию, можно сопоставить синхронному или асинхронному методу с использованием управляемого кода.This is because the messages that make up an operation can be mapped to either synchronous or asynchronous methods when expressed in managed code. Следовательно, если необходимо создать клиент, который вызывает операции асинхронно, можно использовать Svcutil.exe для создания асинхронного кода клиента с помощью параметра /async.Therefore, if you want to build a client that calls operations asynchronously, you can use Svcutil.exe to generate asynchronous client code using the /async option. Дополнительные сведения см. в разделе Практическое руководство. Асинхронный вызов операций службы.For more information, see How to: Call Service Operations Asynchronously.

Вызов служб с использованием клиентских каналов WCFCalling Services Using WCF Client Channels

Типы клиентов WCF расширяют ClientBase<TChannel>, что является производным от System.ServiceModel.IClientChannel интерфейса для предоставления базовой системы каналов.WCF client types extend ClientBase<TChannel>, which itself derives from System.ServiceModel.IClientChannel interface to expose the underlying channel system. Можно вызвать службы с помощью целевого контракта службы с классом System.ServiceModel.ChannelFactory<TChannel>.You can invoke services by using the target service contract with the System.ServiceModel.ChannelFactory<TChannel> class. Дополнительные сведения см. в разделе архитектура клиента WCF.For details, see WCF Client Architecture.

См. такжеSee also