Přehled klienta WCF

Článek
03/02/2024

Tato část popisuje, co klientské aplikace dělají, jak konfigurovat, vytvářet a používat klienta WCF (Windows Communication Foundation) a jak zabezpečit klientské aplikace.

Použití klientských objektů WCF

Klientská aplikace je spravovaná aplikace, která ke komunikaci s jinou aplikací používá klienta WCF. Vytvoření klientské aplikace pro službu WCF vyžaduje následující kroky:

Získejte informace o kontraktu, vazbách a adrese služby pro koncový bod služby.
Pomocí této informace vytvořte klienta WCF.
Operace volání
Zavřete objekt klienta WCF.

Následující části probírají tyto kroky a poskytují stručné úvody k následujícím problémům:

Zpracování chyb
Konfigurace a zabezpečení klientů
Vytváření objektů zpětného volání pro duplexní služby
Asynchronní volání služeb.
Volání služeb pomocí klientských kanálů

Získání kontraktu služby, vazeb a adres

Ve wcf, služby a klienti model kontrakty pomocí spravovaných atributů, rozhraní a metod. Pokud se chcete připojit ke službě v klientské aplikaci, potřebujete získat informace o typu kontraktu služby. Obvykle získáte informace o typu kontraktu služby pomocí nástroje ServiceModel Metadata Utility (Svcutil.exe). Nástroj stáhne metadata ze služby, převede ho do souboru spravovaného zdrojového kódu v jazyce podle vašeho výběru a vytvoří konfigurační soubor klientské aplikace, který můžete použít ke konfiguraci objektu klienta WCF. Pokud například vytvoříte objekt klienta WCF pro vyvolání MyCalculatorServicea víte, že metadata pro tuto službu jsou publikována na http://computerName/MyCalculatorService/Service.svc?wsdladrese , následující příklad kódu ukazuje, jak pomocí Svcutil.exe získat ClientCode.vb soubor, který obsahuje kontrakt služby ve spravovaném kódu.

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

Tento kód kontraktu můžete buď zkompilovat do klientské aplikace, nebo do jiného sestavení, které pak může klientská aplikace použít k vytvoření objektu klienta WCF. Konfigurační soubor můžete použít ke konfiguraci objektu klienta pro správné připojení ke službě .

Příklad tohoto procesu najdete v tématu Postupy: Vytvoření klienta. Podrobnější informace o kontraktech najdete v tématu Kontrakty.

Vytvoření klientského objektu WCF

Klient WCF je místní objekt, který představuje službu WCF ve formě, kterou může klient použít ke komunikaci se vzdálenou službou. Typy klientů WCF implementují cílový kontrakt služby, takže když ho vytvoříte a nakonfigurujete, můžete objekt klienta použít přímo k vyvolání operací služby. Doba běhu WCF převede volání metody na zprávy, odešle je do služby, naslouchá odpovědi a vrátí tyto hodnoty do objektu klienta WCF jako návratové hodnoty nebo outref parametry.

Objekty klientského kanálu WCF můžete také použít pro připojení ke službám a jejich používání. Podrobnosti najdete v tématu Architektura klienta WCF.

Vytvoření nového objektu WCF

Pro ilustraci použití ClientBase<TChannel> třídy předpokládejme, že se z aplikace služby vygeneroval následující jednoduchý kontrakt služby.

Poznámka:

Pokud k vytvoření klienta WCF používáte Visual Studio, objekty se při přidání odkazu na službu do projektu načtou automaticky do prohlížeče objektů.

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

Pokud nepoužíváte Visual Studio, prozkoumejte vygenerovaný kód kontraktu a vyhledejte typ, který rozšiřuje ClientBase<TChannel> a rozhraní ISampleServicekontraktu služby . V tomto případě tento typ vypadá jako následující kód:

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

Tuto třídu lze vytvořit jako místní objekt pomocí jednoho z konstruktorů, konfigurovaných a pak použít pro připojení ke službě typu ISampleService.

Doporučujeme nejprve vytvořit objekt klienta WCF a pak ho použít a zavřít uvnitř jednoho bloku try/catch. Nepoužívejte příkaz using (Using v jazyce Visual Basic), protože může maskovat výjimky v určitých režimech selhání. Další informace najdete v následujících částech a také použití příkazu Zavřít a přerušit k vydání klientských prostředků WCF.

Kontrakty, vazby a adresy

Před vytvořením objektu klienta WCF je nutné nakonfigurovat objekt klienta. Konkrétně musí mít koncový bod služby, který se má použít. Koncový bod je kombinací kontraktu služby, vazby a adresy. (Další informace okoncovýchch Koncové body: Adresy, vazby a kontrakty.) Obvykle se tyto informace nacházejí v elementu koncového <bodu> v konfiguračním souboru klientské aplikace, například v tom, který nástroj Svcutil.exe generuje, a při vytváření klientského objektu se načtou automaticky. Oba typy klientů WCF mají také přetížení, která umožňují programově zadat tyto informace.

Například vygenerovaný konfigurační soubor pro ISampleService použitý v předchozích příkladech obsahuje následující informace o koncovém bodu.

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

Tento konfigurační soubor určuje cílový koncový bod v elementu <client> . Další informace o použití více cílových koncových bodů najdete v ClientBase<TChannel>ChannelFactory<TChannel> konstruktorech.

Operace volání

Jakmile máte vytvořený a nakonfigurovaný objekt klienta, vytvořte blok try/catch, operace volání stejným způsobem, jakým byste objekt vytvořili a zavřeli klientský objekt WCF. Když klientská aplikace volá první operaci, WCF automaticky otevře podkladový kanál a podkladový kanál se zavře při recyklaci objektu. (Případně můžete kanál explicitně otevřít a zavřít před voláním jiných operací nebo ho pak zavřít.)

Pokud máte například následující smlouvu o poskytování služeb:

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

Operace můžete volat vytvořením objektu klienta WCF a voláním jeho metod, jak ukazuje následující příklad kódu. Otevření, volání a zavření klientského objektu WCF probíhá v rámci jednoho bloku try/catch. Další informace naleznete v tématu Přístup ke službám pomocí klienta WCF a použití zavřít a přerušit k vydání prostředků 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();
}

Zpracování chyb

Výjimky můžou nastat v klientské aplikaci při otevření základního klientského kanálu (ať už explicitně nebo automaticky voláním operace), voláním operace pomocí objektu klienta nebo kanálu nebo při zavření základního klientského kanálu. Doporučuje se minimálně, aby aplikace očekávaly zpracování možných System.TimeoutException a System.ServiceModel.CommunicationException výjimek kromě všech System.ServiceModel.FaultException objektů vyvolaných v důsledku chyb PROTOKOLU SOAP vrácených operacemi. Chyby PROTOKOLU SOAP zadané v kontraktu operace se u klientských aplikací generují jako System.ServiceModel.FaultException<TDetail> typ parametru typu podrobný typ chyby SOAP. Další informace o zpracování chybových podmínek v klientské aplikaci naleznete v tématu Odesílání a příjem chyb. Kompletní ukázka ukazuje, jak zpracovat chyby v klientovi, viz Očekávané výjimky.

Konfigurace a zabezpečení klientů

Konfigurace klienta začíná požadovaným načtením informací o cílovém koncovém bodu pro objekt klienta nebo kanálu, obvykle z konfiguračního souboru, i když tyto informace můžete načíst také programově pomocí konstruktorů a vlastností klienta. K povolení určitého chování klienta a pro mnoho scénářů zabezpečení se ale vyžadují další kroky konfigurace.

Například požadavky na zabezpečení pro kontrakty služeb jsou deklarovány v rozhraní kontraktů služeb a pokud Svcutil.exe vytvořil konfigurační soubor, tento soubor obvykle obsahuje vazbu, která dokáže podporovat požadavky na zabezpečení služby. V některých případech se ale může vyžadovat větší konfigurace zabezpečení, například konfigurace přihlašovacích údajů klienta. Úplné informace o konfiguraci zabezpečení pro klienty WCF naleznete v tématu Zabezpečení klientů.

Kromě toho je možné v klientských aplikacích povolit některé vlastní úpravy, například vlastní chování za běhu. Další informace o konfiguraci vlastního chování klienta naleznete v tématu Konfigurace chování klienta.

Vytváření objektů zpětného volání pro duplexní služby

Duplexní služby určují kontrakt zpětného volání, který klientská aplikace musí implementovat, aby poskytovala objekt zpětného volání pro službu, který bude volat podle požadavků smlouvy. I když objekty zpětného volání nejsou úplnými službami (například nemůžete zahájit kanál s objektem zpětného volání), pro účely implementace a konfigurace si je lze představit jako druh služby.

Klienti duplexních služeb musí:

Implementujte třídu kontraktu zpětného volání.
Vytvořte instanci třídy implementace zpětného volání kontraktu a použijte ji k vytvoření objektu System.ServiceModel.InstanceContext , který předáte konstruktoru klienta WCF.
Vyvolá operace a zpracovává zpětná volání operací.

Duplexní klientské objekty WCF fungují jako jejich neduplexní protějšky s výjimkou toho, že zpřístupňují funkce nezbytné pro podporu zpětného volání, včetně konfigurace služby zpětného volání.

Můžete například řídit různé aspekty chování modulu runtime zpětného volání pomocí vlastností System.ServiceModel.CallbackBehaviorAttribute atributu ve třídě zpětného volání. Dalším příkladem je použití System.ServiceModel.Description.CallbackDebugBehavior třídy k povolení vrácení informací o výjimce službám, které volají objekt zpětného volání. Další informace naleznete v tématu Duplex Services. Kompletní ukázku najdete v tématu Duplex.

V počítačích se systémem Windows XP se systémem Internetová informační služba (IIS) 5.1 musí duplexní klienti zadat základní adresu klienta pomocí System.ServiceModel.WSDualHttpBinding třídy nebo je vyvolán výjimka. Následující příklad kódu ukazuje, jak to provést v kódu.

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

Následující kód ukazuje, jak to udělat v konfiguračním souboru.

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

Asynchronní volání služeb

Jak se operace volají, je zcela na vývojáři klienta. Důvodem je to, že zprávy, které tvoří operaci, lze mapovat na synchronní nebo asynchronní metody, pokud jsou vyjádřeny ve spravovaném kódu. Proto pokud chcete sestavit klienta, který volá operace asynchronně, můžete použít Svcutil.exe k vygenerování asynchronního klientského /async kódu pomocí této možnosti. Další informace naleznete v tématu Postupy: Asynchronní volání operací služby.

Volání služeb pomocí klientských kanálů WCF

Typy klientů WCF rozšiřují ClientBase<TChannel>, které sám odvozuje od System.ServiceModel.IClientChannel rozhraní, aby se zpřístupnil základní systém kanálů. Služby můžete vyvolat pomocí cílového kontraktu System.ServiceModel.ChannelFactory<TChannel> služby s třídou. Podrobnosti najdete v tématu Architektura klienta WCF.