Overzicht van WCF-client

In deze sectie wordt beschreven wat clienttoepassingen doen, hoe u een WCF-client (Windows Communication Foundation) configureert, maakt en gebruikt en hoe u clienttoepassingen beveiligt.

WCF-clientobjecten gebruiken

Een clienttoepassing is een beheerde toepassing die gebruikmaakt van een WCF-client om te communiceren met een andere toepassing. Voor het maken van een clienttoepassing voor een WCF-service zijn de volgende stappen vereist:

1. Verkrijg het servicecontract, bindingen en adresgegevens voor een service-eindpunt.

2. Maak een WCF-client met deze informatie.

3. Oproepbewerkingen.

4. Sluit het WCF-clientobject.

In de volgende secties worden deze stappen besproken en worden korte inleiding tot de volgende problemen geboden:

• Fouten afhandelen.

• Clients configureren en beveiligen.

• Callback-objecten maken voor duplexservices.

• Services asynchroon aanroepen.

• Services aanroepen met behulp van clientkanalen.

Het servicecontract, bindingen en adressen verkrijgen

In WCF modelleren services en clients contracten met behulp van beheerde kenmerken, interfaces en methoden. Als u verbinding wilt maken met een service in een clienttoepassing, moet u de typegegevens voor het servicecontract verkrijgen. Normaal gesproken verkrijgt u typegegevens voor het servicecontract met behulp van het hulpprogramma voor metagegevens van ServiceModel (Svcutil.exe). Het hulpprogramma downloadt metagegevens van de service, converteert het naar een beheerd broncodebestand in de taal van uw keuze en maakt een clienttoepassingsconfiguratiebestand dat u kunt gebruiken om uw WCF-clientobject te configureren. Als u bijvoorbeeld een WCF-clientobject maakt om een MyCalculatorServiceaan te roepen en u weet dat de metagegevens voor die service worden gepubliceerd op http://computerName/MyCalculatorService/Service.svc?wsdl, ziet u in het volgende codevoorbeeld hoe u Svcutil.exe gebruikt om een ClientCode.vb bestand te verkrijgen dat het servicecontract in beheerde code bevat.

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

U kunt deze contractcode compileren in de clienttoepassing of in een andere assembly die de clienttoepassing vervolgens kan gebruiken om een WCF-clientobject te maken. U kunt het configuratiebestand gebruiken om het clientobject te configureren om correct verbinding te maken met de service.

Zie Een client maken voor een voorbeeld van dit proces. Zie Contracten voor meer informatie over contracten.

Een WCF-clientobject maken

Een WCF-client is een lokaal object dat een WCF-service vertegenwoordigt in een vorm die de client kan gebruiken om met de externe service te communiceren. WCF-clienttypen implementeren het doelservicecontract, dus wanneer u er een maakt en configureert, kunt u het clientobject vervolgens rechtstreeks gebruiken om servicebewerkingen aan te roepen. De WCF-uitvoeringstijd converteert de methode-aanroepen naar berichten, verzendt deze naar de service, luistert naar het antwoord en retourneert deze waarden naar het WCF-clientobject als retourwaarden of outref parameters.

U kunt ook WCF-clientkanaalobjecten gebruiken om verbinding te maken met en services te gebruiken. Zie WCF-clientarchitectuur voor meer informatie.

Een nieuw WCF-object maken

Als u het gebruik van een ClientBase<TChannel> klasse wilt illustreren, gaat u ervan uit dat het volgende eenvoudige servicecontract is gegenereerd op basis van een servicetoepassing.

Notitie

Als u Visual Studio gebruikt om uw WCF-client te maken, worden objecten automatisch geladen in de objectbrowser wanneer u een serviceverwijzing aan uw project toevoegt.

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

Als u Visual Studio niet gebruikt, bekijkt u de gegenereerde contractcode om het type te vinden dat uitbreidt ClientBase<TChannel> en de interface van het servicecontract ISampleService. In dit geval ziet dat type eruit als de volgende 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);
    }
}

Deze klasse kan worden gemaakt als een lokaal object met behulp van een van de constructors, geconfigureerd en vervolgens gebruikt om verbinding te maken met een service van het type ISampleService.

U wordt aangeraden eerst uw WCF-clientobject te maken en het vervolgens te gebruiken en te sluiten in één try/catch-blok. Gebruik de using instructie (Using in Visual Basic) niet omdat deze uitzonderingen in bepaalde foutmodi kan maskeren. Zie de volgende secties en Gebruik Sluiten en afbreken om WCF-clientresources vrij te geven voor meer informatie.

Contracten, bindingen en adressen

Voordat u een WCF-clientobject kunt maken, moet u het clientobject configureren. Het moet specifiek een service-eindpunt hebben dat moet worden gebruikt. Een eindpunt is de combinatie van een servicecontract, een binding en een adres. (Zie voor meer informatie over eindpunten Eindpunten: adressen, bindingen en contracten.) Deze informatie bevindt zich meestal in het <eindpuntelement> in een clienttoepassingsconfiguratiebestand, zoals het element dat door het hulpprogramma Svcutil.exe wordt gegenereerd en wordt automatisch geladen wanneer u uw clientobject maakt. Beide WCF-clienttypen hebben ook overbelastingen waarmee u deze informatie programmatisch kunt opgeven.

Een gegenereerd configuratiebestand voor een ISampleService bestand dat in de voorgaande voorbeelden wordt gebruikt, bevat bijvoorbeeld de volgende eindpuntgegevens.

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

Dit configuratiebestand specificeert een doeleindpunt in het <client> element. Zie de ClientBase<TChannel> of de ChannelFactory<TChannel> constructors voor meer informatie over het gebruik van meerdere doeleindpunten.

Aanroepende bewerkingen

Zodra u een clientobject hebt gemaakt en geconfigureerd, maakt u een try/catch-blok, roept u bewerkingen aan op dezelfde manier als het object lokaal was en sluit u het WCF-clientobject. Wanneer de clienttoepassing de eerste bewerking aanroept, opent WCF automatisch het onderliggende kanaal en wordt het onderliggende kanaal gesloten wanneer het object wordt gerecycled. (U kunt ook het kanaal expliciet openen en sluiten voor of na het aanroepen van andere bewerkingen.)

Als u bijvoorbeeld het volgende servicecontract hebt:

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  

U kunt bewerkingen aanroepen door een WCF-clientobject te maken en de bijbehorende methoden aan te roepen, zoals in het volgende codevoorbeeld wordt gedemonstreerd. Het openen, aanroepen en sluiten van het WCF-clientobject vindt plaats binnen één try/catch-blok. Zie Accessing Services using a WCF Client and Use Close and Abort to release WCF client resources voor meer informatie.

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

Fouten afhandelen

Er kunnen uitzonderingen optreden in een clienttoepassing bij het openen van het onderliggende clientkanaal (expliciet of automatisch door een bewerking aan te roepen), het client- of kanaalobject te gebruiken om bewerkingen aan te roepen of bij het sluiten van het onderliggende clientkanaal. Het wordt aanbevolen om minimaal te verwachten dat toepassingen mogelijke System.TimeoutException en uitzonderingen verwerken, System.ServiceModel.CommunicationException naast objecten System.ServiceModel.FaultException die worden gegenereerd als gevolg van SOAP-fouten die worden geretourneerd door bewerkingen. SOAP-fouten die zijn opgegeven in het bewerkingscontract, worden gegenereerd voor clienttoepassingen, omdat System.ServiceModel.FaultException<TDetail> de typeparameter het detailtype van de SOAP-fout is. Zie Fouten verzenden en ontvangen voor meer informatie over het afhandelen van foutvoorwaarden in een clienttoepassing. Zie Verwachte uitzonderingen voor een volledig voorbeeld van de instructies voor het afhandelen van fouten in een client.

Clients configureren en beveiligen

Het configureren van een client begint met het vereiste laden van doeleindpuntgegevens voor het client- of kanaalobject, meestal vanuit een configuratiebestand, hoewel u deze informatie ook programmatisch kunt laden met behulp van de clientconstructors en -eigenschappen. Er zijn echter aanvullende configuratiestappen vereist om bepaald clientgedrag en voor veel beveiligingsscenario's in te schakelen.

Beveiligingsvereisten voor servicecontracten worden bijvoorbeeld gedeclareerd in de servicecontractinterface en als Svcutil.exe een configuratiebestand hebt gemaakt, bevat dat bestand meestal een binding die de beveiligingsvereisten van de service kan ondersteunen. In sommige gevallen is er echter mogelijk meer beveiligingsconfiguratie vereist, zoals het configureren van clientreferenties. Zie Clients beveiligen voor volledige informatie over de configuratie van beveiliging voor WCF-clients.

Daarnaast kunnen sommige aangepaste wijzigingen worden ingeschakeld in clienttoepassingen, zoals aangepaste runtimegedrag. Zie Clientgedrag configureren voor meer informatie over het configureren van aangepast clientgedrag.

Callback-objecten maken voor duplexservices

Duplex-services geven een callbackcontract op dat door de clienttoepassing moet worden geïmplementeerd om een callback-object te bieden voor de service die moet worden aangeroepen volgens de vereisten van het contract. Hoewel callback-objecten geen volledige services zijn (u kunt bijvoorbeeld geen kanaal met een callback-object initiëren), kunnen ze voor de implementatie en configuratie worden beschouwd als een soort service.

Clients van duplex-services moeten:

• Implementeer een callback-contractklasse.

• Maak een exemplaar van de callback-contract-implementatieklasse en gebruik deze om het System.ServiceModel.InstanceContext object te maken dat u doorgeeft aan de WCF-clientconstructor.

• Aanroepen van bewerkingen en callbacks voor bewerkingen verwerken.

Duplex WCF-clientobjecten werken net als hun nonduplex-tegenhangers, met uitzondering dat ze de functionaliteit beschikbaar maken die nodig is om callbacks te ondersteunen, met inbegrip van de configuratie van de callback-service.

U kunt bijvoorbeeld verschillende aspecten van het runtimegedrag van callback-objecten beheren met behulp van eigenschappen van het System.ServiceModel.CallbackBehaviorAttribute kenmerk in de callback-klasse. Een ander voorbeeld is het gebruik van de System.ServiceModel.Description.CallbackDebugBehavior klasse om het retourneren van uitzonderingsgegevens in te schakelen voor services die het callback-object aanroepen. Zie Duplex Services voor meer informatie. Zie Duplex voor een volledig voorbeeld.

Op Windows XP-computers waarop IIS (Internet Information Services) 5.1 wordt uitgevoerd, moeten duplex-clients een clientbasisadres opgeven met behulp van de System.ServiceModel.WSDualHttpBinding klasse of een uitzondering wordt gegenereerd. In het volgende codevoorbeeld ziet u hoe u dit doet 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/")

De volgende code laat zien hoe u dit doet in een configuratiebestand

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

Services asynchroon aanroepen

Hoe bewerkingen worden aangeroepen, is volledig aan de clientontwikkelaar. Dit komt doordat de berichten waaruit een bewerking bestaat, kunnen worden toegewezen aan synchrone of asynchrone methoden wanneer ze worden uitgedrukt in beheerde code. Als u daarom een client wilt bouwen die bewerkingen asynchroon aanroept, kunt u Svcutil.exe gebruiken om asynchrone clientcode te genereren met behulp van de /async optie. Zie Procedure voor meer informatie : Servicebewerkingen asynchroon aanroepen.

Services aanroepen met WCF-clientkanalen

WCF-clienttypen worden uitgebreid ClientBase<TChannel>, die zelf zijn afgeleid van System.ServiceModel.IClientChannel de interface om het onderliggende kanaalsysteem beschikbaar te maken. U kunt services aanroepen met behulp van het doelservicecontract met de System.ServiceModel.ChannelFactory<TChannel> klasse. Zie WCF-clientarchitectuur voor meer informatie.

Zie ook

• System.ServiceModel.ClientBase<TChannel>
• System.ServiceModel.ChannelFactory<TChannel>