Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
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:
Verkrijg het servicecontract, bindingen en adresgegevens voor een service-eindpunt.
Maak een WCF-client met deze informatie.
Telefoonoperaties.
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 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 runtime van WCF zet de methode-aanroepen om in berichten, verzendt ze naar de service, luistert naar het antwoord en retourneert die waarden naar het WCF-clientobject als retourwaarden of out of ref 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.
Opmerking
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, onderzoekt u de gegenereerde contractcode om het type te vinden dat ClientBase<TChannel> uitbreidt 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. Voor meer informatie, zie de volgende secties en Gebruik Sluiten en afbreken om WCF-clientresources vrij te geven.
Contracten, verbintenissen en adressen
Voordat u een WCF-clientobject kunt maken, moet u het clientobject configureren. Het moet een specifiek service-eindpunt hebben om te worden gebruikt. Een eindpunt is de combinatie van een servicecontract, een binding en een adres. (Zie Eindpunten: Adressen, Bindingen en Contracten voor meer informatie over eindpunten.) 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.
Oproepen van operaties
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. Voor meer informatie, zie Toegang tot services met een WCF-client en Gebruik Close en Abort om WCF-clientresources vrij te geven.
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 dat toepassingen minimaal voorbereid zijn op het afhandelen van mogelijke System.TimeoutException en System.ServiceModel.CommunicationException-uitzonderingen, naast objecten System.ServiceModel.FaultException die worden gegooid als gevolg van SOAP-fouten die door bewerkingen worden geretourneerd. SOAP-fouten die in het bewerkingscontract zijn gespecificeerd, worden aan clienttoepassingen gepresenteerd als een System.ServiceModel.FaultException<TDetail>, waarbij 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 interface van het servicecontract 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.
Klanten van duplexdiensten 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. Voor meer informatie, zie Hoe: Servicebewerkingen asynchroon aanroepen.
Oproepen van services met WCF-clientkanalen
WCF-clienttypen breiden ClientBase<TChannel> uit, die zelf is afgeleid van de System.ServiceModel.IClientChannel-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.