Översikt över WCF-klienten

Artikel
06/08/2023

I det här avsnittet beskrivs vad klientprogram gör, hur du konfigurerar, skapar och använder en WCF-klient (Windows Communication Foundation) och hur du skyddar klientprogram.

Använda WCF-klientobjekt

Ett klientprogram är ett hanterat program som använder en WCF-klient för att kommunicera med ett annat program. Följande steg krävs för att skapa ett klientprogram för en WCF-tjänst:

Hämta tjänstkontrakt, bindningar och adressinformation för en tjänstslutpunkt.
Skapa en WCF-klient med hjälp av den informationen.
Anropsåtgärder.
Stäng WCF-klientobjektet.

Följande avsnitt beskriver dessa steg och ger korta introduktioner till följande problem:

Hantera fel.
Konfigurera och skydda klienter.
Skapa motringningsobjekt för duplex-tjänster.
Anropa tjänster asynkront.
Anropa tjänster med hjälp av klientkanaler.

Hämta tjänstkontraktet, bindningarna och adresserna

I WCF modellerar tjänster och klienter kontrakt med hanterade attribut, gränssnitt och metoder. Om du vill ansluta till en tjänst i ett klientprogram måste du hämta typinformationen för tjänstkontraktet. Vanligtvis hämtar du typinformation för tjänstkontraktet med hjälp av servicemodelmetadataverktyget (Svcutil.exe). Verktyget laddar ned metadata från tjänsten, konverterar den till en hanterad källkodsfil på valfritt språk och skapar en konfigurationsfil för klientprogrammet som du kan använda för att konfigurera ditt WCF-klientobjekt. Om du till exempel ska skapa ett WCF-klientobjekt för att anropa en MyCalculatorService, och du vet att metadata för tjänsten publiceras på http://computerName/MyCalculatorService/Service.svc?wsdl, visar följande kodexempel hur du använder Svcutil.exe för att hämta en ClientCode.vb fil som innehåller tjänstkontraktet i hanterad kod.

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

Du kan antingen kompilera den här kontraktskoden till klientprogrammet eller till en annan sammansättning som klientprogrammet sedan kan använda för att skapa ett WCF-klientobjekt. Du kan använda konfigurationsfilen för att konfigurera klientobjektet så att det ansluter korrekt till tjänsten .

Ett exempel på den här processen finns i Så här skapar du en klient. Mer fullständig information om kontrakt finns i Kontrakt.

Skapa ett WCF-klientobjekt

En WCF-klient är ett lokalt objekt som representerar en WCF-tjänst i ett formulär som klienten kan använda för att kommunicera med fjärrtjänsten. WCF-klienttyper implementerar måltjänstkontraktet, så när du skapar ett och konfigurerar det kan du sedan använda klientobjektet direkt för att anropa tjänståtgärder. WCF-körningstiden konverterar metodanropen till meddelanden, skickar dem till tjänsten, lyssnar efter svaret och returnerar dessa värden till WCF-klientobjektet som returvärden eller out parametrar ref .

Du kan också använda WCF-klientkanalobjekt för att ansluta till och använda tjänster. Mer information finns i WCF-klientarkitektur.

Skapa ett nytt WCF-objekt

För att illustrera användningen av en ClientBase<TChannel> klass antar du att följande enkla tjänstkontrakt har genererats från ett tjänstprogram.

Kommentar

Om du använder Visual Studio för att skapa din WCF-klient läses objekt in automatiskt i objektwebbläsaren när du lägger till en tjänstreferens i projektet.

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

Om du inte använder Visual Studio undersöker du den genererade kontraktskoden för att hitta den typ som utökas ClientBase<TChannel> och tjänstkontraktsgränssnittet ISampleService. I det här fallet ser den typen ut som följande kod:

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

Den här klassen kan skapas som ett lokalt objekt med någon av konstruktorerna, konfigurerad och sedan användas för att ansluta till en tjänst av typen ISampleService.

Vi rekommenderar att du först skapar WCF-klientobjektet och sedan använder det och stänger det i ett enda try/catch-block. Använd inte -instruktionen using (Using i Visual Basic) eftersom den kan maskera undantag i vissa fellägen. Mer information finns i följande avsnitt samt Använd Stäng och Avbryt för att frigöra WCF-klientresurser.

Kontrakt, bindningar och adresser

Innan du kan skapa ett WCF-klientobjekt måste du konfigurera klientobjektet. Mer specifikt måste den ha en tjänstslutpunkt att använda. En slutpunkt är kombinationen av ett tjänstkontrakt, en bindning och en adress. (Mer information om slutpunkter finns i Slutpunkter: Adresser, bindningar och kontrakt.) Den här informationen finns vanligtvis i <slutpunktselementet> i en klientprogramkonfigurationsfil, till exempel den som Svcutil.exe verktyget genererar och läses in automatiskt när du skapar klientobjektet. Båda WCF-klienttyperna har också överlagringar som gör att du programmatiskt kan ange den här informationen.

En genererad konfigurationsfil för en ISampleService som används i föregående exempel innehåller till exempel följande slutpunktsinformation.

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

Den här konfigurationsfilen anger en målslutpunkt i elementet <client> . Mer information om hur du använder flera målslutpunkter finns i ClientBase<TChannel> konstruktorerna eller ChannelFactory<TChannel> .

Anropande åtgärder

När du har skapat och konfigurerat ett klientobjekt skapar du ett try/catch-block, anropar åtgärder på samma sätt som om objektet var lokalt och stänger WCF-klientobjektet. När klientprogrammet anropar den första åtgärden öppnar WCF automatiskt den underliggande kanalen och den underliggande kanalen stängs när objektet återvinns. (Du kan också uttryckligen öppna och stänga kanalen före eller efter anrop till andra åtgärder.)

Om du till exempel har följande tjänstkontrakt:

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

Du kan anropa åtgärder genom att skapa ett WCF-klientobjekt och anropa dess metoder, vilket visas i följande kodexempel. Öppnandet, anropet och stängningen av WCF-klientobjektet sker inom ett enda try/catch-block. Mer information finns i Accessing Services Using a WCF Client (Åtkomst till tjänster med hjälp av en WCF-klient ) och Använd Stäng och Avbryt för att frigöra WCF-klientresurser.

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

Hantera fel

Undantag kan inträffa i ett klientprogram när du öppnar den underliggande klientkanalen (antingen explicit eller automatiskt genom att anropa en åtgärd), använda klienten eller kanalobjektet för att anropa åtgärder eller när den underliggande klientkanalen stängs. Det rekommenderas som minst att program förväntar sig att hantera möjliga System.TimeoutException och System.ServiceModel.CommunicationException undantag utöver objekt System.ServiceModel.FaultException som genereras till följd av SOAP-fel som returneras av åtgärder. SOAP-fel som anges i åtgärdskontraktet genereras till klientprogram som en System.ServiceModel.FaultException<TDetail> där typparametern är detaljtypen för SOAP-felet. Mer information om hur du hanterar feltillstånd i ett klientprogram finns i Skicka och ta emot fel. Ett fullständigt exempel på hur du hanterar fel i en klient finns i Förväntade undantag.

Konfigurera och skydda klienter

Konfigurationen av en klient börjar med nödvändig inläsning av målslutpunktsinformation för klient- eller kanalobjektet, vanligtvis från en konfigurationsfil, men du kan också läsa in den här informationen programmatiskt med hjälp av klientkonstruktorerna och egenskaperna. Ytterligare konfigurationssteg krävs dock för att aktivera vissa klientbeteenden och för många säkerhetsscenarier.

Till exempel deklareras säkerhetskrav för tjänstkontrakt i tjänstkontraktsgränssnittet, och om Svcutil.exe skapat en konfigurationsfil innehåller filen vanligtvis en bindning som kan stödja tjänstens säkerhetskrav. I vissa fall kan det dock krävas mer säkerhetskonfiguration, till exempel att konfigurera klientautentiseringsuppgifter. Fullständig information om konfigurationen av säkerhet för WCF-klienter finns i Skydda klienter.

Dessutom kan vissa anpassade ändringar aktiveras i klientprogram, till exempel anpassade körningsbeteenden. Mer information om hur du konfigurerar ett anpassat klientbeteende finns i Konfigurera klientbeteenden.

Skapa motringningsobjekt för Duplex Services

Duplex-tjänster anger ett återanropskontrakt som klientprogrammet måste implementera för att tillhandahålla ett återanropsobjekt för tjänsten som ska anropas enligt kraven i kontraktet. Även om motringningsobjekt inte är fullständiga tjänster (du kan till exempel inte initiera en kanal med ett motringningsobjekt) kan de för implementering och konfiguration betraktas som en typ av tjänst.

Klienter för duplex-tjänster måste:

Implementera en samtalskontraktsklass.
Skapa en instans av implementeringsklassen för återanropskontrakt och använd den för att skapa System.ServiceModel.InstanceContext objektet som du skickar till WCF-klientkonstruktorn.
Anropa åtgärder och hantera återanrop till åtgärder.

Duplex WCF-klientobjekt fungerar som deras icke-dubbelsidiga motsvarigheter, med undantag för att de exponerar de funktioner som krävs för återanrop, inklusive konfigurationen av återanropstjänsten.

Du kan till exempel styra olika aspekter av körningsbeteendet för motringningsobjekt med hjälp av egenskaperna för System.ServiceModel.CallbackBehaviorAttribute attributet i motringningsklassen. Ett annat exempel är användningen av System.ServiceModel.Description.CallbackDebugBehavior klassen för att aktivera retur av undantagsinformation till tjänster som anropar motringningsobjektet. Mer information finns i Duplex Services. Ett fullständigt exempel finns i Duplex.

På Windows XP-datorer som kör Internet Information Services (IIS) 5.1 måste duplex-klienter ange en klientbasadress med hjälp av System.ServiceModel.WSDualHttpBinding klassen eller så utlöses ett undantag. I följande kodexempel visas hur du gör detta i kod.

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

Följande kod visar hur du gör detta i en konfigurationsfil

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

Anropa tjänster asynkront

Hur åtgärder anropas är helt upp till klientutvecklaren. Det beror på att de meddelanden som utgör en åtgärd kan mappas till synkrona eller asynkrona metoder när de uttrycks i hanterad kod. Om du vill skapa en klient som anropar åtgärder asynkront kan du därför använda Svcutil.exe för att generera asynkron klientkod med hjälp av /async alternativet . Mer information finns i Så här anropar du tjänståtgärder asynkront.

Anropa tjänster med WCF-klientkanaler

WCF-klienttyper utökar ClientBase<TChannel>, vilket i sig härleds från System.ServiceModel.IClientChannel gränssnittet för att exponera det underliggande kanalsystemet. Du kan anropa tjänster med hjälp av måltjänstkontraktet System.ServiceModel.ChannelFactory<TChannel> med klassen . Mer information finns i WCF-klientarkitektur.

Dela via