Udostępnij za pośrednictwem

Omówienie klienta programu WCF

W tej sekcji opisano, co robią aplikacje klienckie, jak konfigurować, tworzyć i używać klienta programu Windows Communication Foundation (WCF) oraz jak zabezpieczyć aplikacje klienckie.

Korzystanie z obiektów klienta programu WCF

Aplikacja kliencka to aplikacja zarządzana, która używa klienta WCF do komunikowania się z inną aplikacją. Utworzenie aplikacji klienckiej dla usługi WCF wymaga wykonania następujących czynności:

  1. Uzyskaj kontrakt usługi, powiązania i informacje o adresie punktu końcowego usługi.

  2. Utwórz klienta programu WCF przy użyciu tych informacji.

  3. Operacje połączeń

  4. Zamknij obiekt klienta programu WCF.

W poniższych sekcjach omówiono te kroki i przedstawiono krótkie wprowadzenie do następujących problemów:

  • Obsługa błędów.

  • Konfigurowanie i zabezpieczanie klientów.

  • Tworzenie obiektów wywołania zwrotnego dla usług dwukierunkowych.

  • Asynchroniczne wywoływanie usług.

  • Wywoływanie usług przy użyciu kanałów klienta.

Uzyskaj umowę serwisową, powiązania i adresy

W WCF usługi i klienci modelują kontrakty przy użyciu atrybutów zarządzanych, interfejsów i metod. Aby nawiązać połączenie z usługą w aplikacji klienckiej, musisz uzyskać informacje o typie kontraktu usługi. Zazwyczaj uzyskujesz informacje o typie dla kontraktu usługi przy użyciu narzędzia ServiceModel Metadata Tool (Svcutil.exe). Narzędzie pobiera metadane z usługi, konwertuje je na zarządzany plik kodu źródłowego w wybranym języku i tworzy plik konfiguracji aplikacji klienckiej, którego można użyć do skonfigurowania obiektu klienta WCF. Na przykład, jeśli zamierzasz utworzyć obiekt klienta WCF w celu wywołania MyCalculatorService, i wiesz, że metadane dla tej usługi są publikowane pod adresem http://computerName/MyCalculatorService/Service.svc?wsdl, poniższy przykład kodu pokazuje, jak użyć Svcutil.exe, aby uzyskać plik ClientCode.vb zawierający kontrakt usługi w kodu zarządzanego.

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

Ten kod kontraktu można skompilować do aplikacji klienckiej lub do innego zestawu, którego aplikacja kliencka może następnie użyć do utworzenia obiektu klienta WCF. Możesz użyć pliku konfiguracji, aby skonfigurować obiekt klienta, aby prawidłowo nawiązać połączenie z usługą .

Aby zapoznać się z przykładem tego procesu, zobacz Instrukcje: tworzenie klienta. Aby uzyskać więcej informacji na temat kontraktów, zobacz Kontrakty.

Tworzenie obiektu klienta programu WCF

Klient WCF jest obiektem lokalnym reprezentującym usługę WCF w postaci, za pomocą którego klient może komunikować się z usługą zdalną. Typy klientów programu WCF implementują docelowy kontrakt usługi, więc podczas tworzenia jednego i konfigurowania go można użyć obiektu klienta bezpośrednio do wywoływania operacji usługi. Środowisko uruchomieniowe WCF konwertuje wywołania metod na komunikaty, wysyła je do usługi, nasłuchuje na odpowiedzi i zwraca te wartości do obiektu klienta WCF jako wartości zwracane lub parametry out lub ref.

Można również używać obiektów kanału klienta WCF do nawiązywania połączenia z usługami i korzystania z nich. Aby uzyskać szczegółowe informacje, zobacz Architektura klienta WCF.

Tworzenie nowego obiektu WCF

Aby zilustrować użycie ClientBase<TChannel> klasy, załóżmy, że na podstawie aplikacji usługi wygenerowano następujący prosty kontrakt usługi.

Uwaga / Notatka

Jeśli używasz programu Visual Studio do tworzenia klienta WCF, obiekty są ładowane automatycznie do przeglądarki obiektów podczas dodawania odwołania do usługi do projektu.

[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);
}

Jeśli nie używasz Visual Studio, sprawdź wygenerowany kod kontraktu, aby znaleźć typ, który rozszerza ClientBase<TChannel> i interfejs kontraktu usługi ISampleService. W takim przypadku ten typ wygląda następująco:

[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);
    }
}

Tę klasę można utworzyć jako obiekt lokalny przy użyciu jednego z konstruktorów, skonfigurowanych, a następnie użyć do nawiązania połączenia z usługą typu ISampleService.

Zaleca się, aby najpierw utworzyć obiekt klienta WCF, a następnie użyć go i zamknąć wewnątrz jednego bloku try/catch. Nie używaj instrukcji using (Using w Visual Basic), ponieważ może maskować wyjątki w niektórych trybach awarii. Aby uzyskać więcej informacji, zobacz poniższe sekcje, a także Użyj poleceń Zamknij i Abort, aby zwolnić zasoby klienta WCF.

Kontrakty, powiązania i adresy

Przed utworzeniem obiektu klienta programu WCF należy skonfigurować obiekt klienta. W szczególności musi mieć punkt końcowy usługi do użycia. Punkt końcowy to kombinacja kontraktu usługi, powiązania i adresu. (Aby uzyskać więcej informacji na temat punktów końcowych, zobacz Punkty końcowe: adresy, powiązania i kontrakty). Zazwyczaj te informacje znajdują się w <elemecie punktu końcowego> w pliku konfiguracji aplikacji klienckiej, takim jak to, które generuje narzędzie Svcutil.exe, i jest ładowane automatycznie podczas tworzenia obiektu klienta. Oba typy klientów programu WCF mają również przeciążenia, które umożliwiają programowe określanie tych informacji.

Na przykład wygenerowany plik konfiguracji dla ISampleService, używany w poprzednich przykładach, zawiera następujące informacje o punkcie końcowym.

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

Ten plik konfiguracji określa docelowy punkt końcowy w elemecie <client> . Aby uzyskać więcej informacji na temat korzystania z wielu docelowych punktów końcowych, zobacz konstruktory ClientBase<TChannel> lub ChannelFactory<TChannel>.

Wywoływanie operacji

Po utworzeniu i skonfigurowaniu obiektu klienta utwórz blok try/catch, wywołaj operacje w taki sam sposób, jak w przypadku obiektu lokalnego i zamknij obiekt klienta programu WCF. Gdy aplikacja kliencka wywołuje pierwszą operację, program WCF automatycznie otwiera kanał źródłowy, a bazowy kanał jest zamykany po recyklingu obiektu. (Alternatywnie można jawnie otworzyć i zamknąć kanał przed lub po wywołaniu innych operacji).

Jeśli na przykład masz następującą umowę usługi:

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

Operacje można wywoływać, tworząc obiekt klienta WCF i wywołując jego metody, jak pokazano w poniższym przykładzie kodu. Otwieranie, wywoływanie i zamykanie obiektu klienta programu WCF odbywa się w ramach pojedynczego bloku try/catch. Aby uzyskać więcej informacji, zobacz Uzyskiwanie dostępu do usług przy użyciu klienta WCF i Użyj Zamykania i Przerwania, aby zwolnić zasoby klienta 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();
}

Obsługa błędów

Wyjątki mogą wystąpić w aplikacji klienckiej podczas otwierania bazowego kanału klienta (jawnego lub automatycznego przez wywołanie operacji) przy użyciu klienta lub obiektu kanału w celu wywołania operacji lub podczas zamykania bazowego kanału klienta. Zaleca się co najmniej, aby aplikacje oczekiwały obsługi możliwych System.TimeoutException i System.ServiceModel.CommunicationException wyjątków oprócz wszystkich obiektów System.ServiceModel.FaultException zgłaszanych w wyniku błędów SOAP zwracanych przez operacje. Błędy protokołu SOAP określone w kontrakcie operacji są przekazywane do aplikacji klienckich jako System.ServiceModel.FaultException<TDetail>, gdzie parametr typu jest szczegółowym typem błędu SOAP. Aby uzyskać więcej informacji na temat obsługi warunków błędów w aplikacji klienckiej, zobacz Wysyłanie i odbieranie błędów. Pełny przykład pokazuje, jak obsługiwać błędy w kliencie, zobacz Oczekiwane wyjątki.

Konfigurowanie i zabezpieczanie klientów

Skonfigurowanie klienta rozpoczyna się od wymaganego ładowania informacji o docelowym punkcie końcowym dla klienta lub obiektu kanału, zazwyczaj z pliku konfiguracji, chociaż te informacje można również załadować programowo przy użyciu konstruktorów i właściwości klienta. Jednak dodatkowe kroki konfiguracji są wymagane do włączenia określonego zachowania klienta i w przypadku wielu scenariuszy zabezpieczeń.

Na przykład wymagania dotyczące zabezpieczeń kontraktów usług są określone w interfejsie kontraktu usługi, a jeśli Svcutil.exe utworzył plik konfiguracji, ten plik zwykle zawiera powiązanie, które może obsługiwać wymagania dotyczące zabezpieczeń usługi. W niektórych przypadkach może być jednak wymagana większa konfiguracja zabezpieczeń, na przykład konfigurowanie poświadczeń klienta. Aby uzyskać pełne informacje na temat konfiguracji zabezpieczeń dla klientów WCF, zobacz Zabezpieczanie klientów.

Ponadto niektóre niestandardowe modyfikacje można włączyć w aplikacjach klienckich, takich jak niestandardowe zachowania podczas działania. Aby uzyskać więcej informacji na temat konfigurowania niestandardowego zachowania klienta, zobacz Konfigurowanie zachowań klientów.

Tworzenie obiektów wywołania zwrotnego dla usług dwukierunkowych

Usługi dwustronne określają kontrakt wywołania zwrotnego, który aplikacja kliencka musi zaimplementować w celu zapewnienia obiektu wywołania zwrotnego dla usługi w celu wywołania zgodnie z wymaganiami umowy. Chociaż obiekty wywołania zwrotnego nie są pełnymi usługami (na przykład nie można zainicjować kanału z obiektem wywołania zwrotnego), do celów implementacji i konfiguracji można je traktować jako rodzaj usługi.

Klienci usług dwukierunkowych muszą:

  • Zaimplementuj klasę kontraktu typu callback.

  • Utwórz wystąpienie klasy implementującej kontrakt wywołania zwrotnego i użyj go, aby stworzyć obiekt System.ServiceModel.InstanceContext, który jest następnie przekazywany do konstruktora klienta WCF.

  • Wywoływanie operacji i obsługa wywołań zwrotnych operacji.

Dwukierunkowe obiekty klienta WCF działają podobnie jak ich jednostronne odpowiedniki, z wyjątkiem tego, że udostępniają funkcjonalność niezbędną do obsługi wywołań zwrotnych, w tym konfigurację usługi zwrotnej.

Można na przykład kontrolować różne aspekty zachowania środowiska uruchomieniowego obiektu wywołania zwrotnego przy użyciu właściwości atrybutu System.ServiceModel.CallbackBehaviorAttribute w klasie wywołania zwrotnego. Innym przykładem jest użycie System.ServiceModel.Description.CallbackDebugBehavior klasy w celu umożliwienia zwracania informacji o wyjątku do usług wywołujących obiekt wywołania zwrotnego. Aby uzyskać więcej informacji, zobacz Duplex Services. Aby zapoznać się z kompletnym przykładem, zobacz Dupleks.

Na komputerach z systemem Windows XP z usługą Internet Information Services (IIS) 5.1, klienci typu duplex muszą określić adres podstawowy klienta przy użyciu klasy System.ServiceModel.WSDualHttpBinding, w przeciwnym razie zostanie zgłoszony wyjątek. Poniższy przykład kodu pokazuje, jak to zrobić w kodzie.

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

Poniższy kod pokazuje, jak to zrobić w pliku konfiguracji

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

Wywoływanie usług w sposób asynchroniczny

Całkowicie od programisty aplikacji klienckiej zależy sposób, w jaki są wywoływane operacje. Jest to spowodowane tym, że komunikaty tworzące operację mogą być mapowane na metody synchroniczne lub asynchroniczne, gdy są wyrażane w kodzie zarządzanym. W związku z tym, jeśli chcesz utworzyć klienta, który wywołuje operacje asynchronicznie, możesz użyć Svcutil.exe do wygenerowania asynchronicznego kodu klienta przy użyciu /async opcji . Aby uzyskać więcej informacji, zobacz Jak wykonywać operacje serwisowe asynchronicznie.

Wywoływanie usług przy użyciu kanałów klienta programu WCF

Typy klientów programu WCF rozszerzają ClientBase<TChannel>, pochodzące od interfejsu System.ServiceModel.IClientChannel, aby uwidocznić podstawowy system kanałów. Usługi można wywoływać przy użyciu kontraktu usługi docelowej z klasą System.ServiceModel.ChannelFactory<TChannel> . Aby uzyskać szczegółowe informacje, zobacz Architektura klienta WCF.

Zobacz także