Omówienie klienta programu WCF

Artykuł
03/02/2024

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:

Uzyskaj kontrakt usługi, powiązania i informacje o adresie punktu końcowego usługi.
Utwórz klienta programu WCF przy użyciu tych informacji.
Operacje wywoływania.
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.

Uzyskiwanie kontraktu usługi, powiązań i adresów

W programie WCF kontrakty modelu usług i klientów 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 Utility 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. Jeśli na przykład utworzysz obiekt klienta programu WCF w celu wywołania MyCalculatorServiceelementu i wiesz, że metadane dla tej usługi są publikowane w http://computerName/MyCalculatorService/Service.svc?wsdlwitrynie , poniższy przykład kodu pokazuje, jak używać Svcutil.exe do uzyskania ClientCode.vb pliku zawierającego kontrakt usługi w kodzie zarządzanym.

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. Czas wykonywania programu WCF konwertuje wywołania metody na komunikaty, wysyła je do usługi, nasłuchuje odpowiedzi i zwraca te wartości do obiektu klienta WCF jako zwracane wartości lub outref parametry.

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

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 programu Visual Studio, sprawdź wygenerowany kod kontraktu, aby znaleźć typ rozszerzający ClientBase<TChannel> i interfejs ISampleServicekontraktu usługi . 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ę najpierw utworzenie obiektu klienta WCF, a następnie użycie go i zamknięcie wewnątrz pojedynczego 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 zamknij i abort do wydania zasobów klienta programu 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 połączenie 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 używany ISampleService 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 ClientBase<TChannel> konstruktory 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 Accessing Services Using a WCF Client and Use Close and Abort to release WCF client resources (Uzyskiwanie dostępu do usług przy użyciu klienta WCF) i Use Close and Abort to release WCF client resources (Uzyskiwanie dostępu do usług przy użyciu klienta WCF) i Use Close and Abort to release WCF client resources (Używanie zamykania i przerwa

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 System.ServiceModel.FaultException obiektów zgłaszanych w wyniku błędów protokołu SOAP zwracanych przez operacje. Błędy protokołu SOAP określone w kontrakcie operacji są wywoływane do aplikacji klienckich jako miejsca, w którym parametr typu jest typem System.ServiceModel.FaultException<TDetail> szczegółów błędu PROTOKOŁU 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ą deklarowane 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 w czasie wykonywania. 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 dwuduplekowych

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 wywołania zwrotnego.
Utwórz wystąpienie klasy implementacji kontraktu wywołania zwrotnego i użyj go do utworzenia System.ServiceModel.InstanceContext obiektu przekazanego do konstruktora klienta WCF.
Wywoływanie operacji i obsługa wywołań zwrotnych operacji.

Dwukierunkowe obiekty klienta WCF działają jak ich odpowiedniki niezwiązane, z wyjątkiem, że uwidaczniają funkcje niezbędne do obsługi wywołań zwrotnych, w tym konfiguracji usługi wywołania zwrotnego.

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 Usługi dwustronne. Aby zapoznać się z kompletnym przykładem, zobacz Dupleks.

Na komputerach z systemem Windows XP z usługami Internet Information Services (IIS) 5.1 klienci dupleksu muszą określić adres podstawowy klienta przy użyciu System.ServiceModel.WSDualHttpBinding klasy lub zgłaszany jest 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>

Asynchroniczne wywoływanie usług

Wywoływanie operacji zależy całkowicie od dewelopera klienta. 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 kodu klienta asynchronicznego przy użyciu /async opcji . Aby uzyskać więcej informacji, zobacz How to: Call Service Operations Asynchronously (Jak wywoływać operacje usługi asynchronicznie).

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

Typy klientów programu WCF rozszerzają system ClientBase<TChannel>, który pochodzi z System.ServiceModel.IClientChannel interfejsu w celu uwidocznienia bazowego systemu 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.