Übersicht über den WCF-Client

In diesem Abschnitt werden die von Clientanwendungen ausgeführten Aktionen sowie das Konfigurieren, Erstellen und Verwenden eines Windows Communication Foundation (WCF)-Clients und das Sichern von Clientanwendungen erläutert.

Verwenden von WCF-Clientobjekten

Eine Clientanwendung ist eine verwaltete Anwendung, die einen WCF-Client zur Kommunikation mit anderen Anwendungen verwendet. Das Erstellen einer Clientanwendung für einen WCF-Dienst erfordert die folgenden Schritte:

  1. Abrufen des Dienstvertrags, der Bindungen und der Adressinformationen für einen Dienstendpunkt.

  2. Erstellen eines WCF-Clients mithilfe dieser Informationen.

  3. Aufrufen von Vorgängen.

  4. Schließen des WCF-Clientobjekts.

In den folgenden Abschnitten finden Sie eine Erläuterung dieser Schritte und kurze Einführungen in die folgenden Probleme:

  • Behandeln von Fehlern.

  • Konfigurieren und Sichern von Clients.

  • Erstellen von Rückrufobjekten für Duplexdienste

  • Asynchrones Aufrufen von Diensten.

  • Aufrufen von Diensten mithilfe von Clientkanälen.

Abrufen von Dienstvertrag, Bindungen und Adressen

In WCF Dienst- und Clientmodellverträge mit verwalteten Attributen, Schnittstellen und Methoden. Soll eine Verbindung zu einem Dienst in einer Clientanwendung hergestellt werden, muss der Informationstyp für den Dienstvertrag abgerufen werden. In der Regel Sie dazu die ServiceModel Metadata Utility Tool (Svcutil.exe), Herunterladen von Metadaten aus dem Dienst, konvertiert es auf einem verwalteten Quellcode Datei in der Sprache Ihrer Wahl, und erstellt eine Konfigurationsdatei der Clientanwendung, können Sie konfigurieren die WCF Clientobjekt. Falls Sie beispielsweise ein WCF-Clientobjekt erstellen, um MyCalculatorService aufzurufen und wissen, dass die Metadaten für diesen Dienst unter http://computerName/MyCalculatorService/Service.svc?wsdl veröffentlicht werden, wird im folgenden Codebeispiel die Verwendung von Svcutil.exe zum Abrufen einer Datei vom Typ ClientCode.vb gezeigt, die den Dienstvertrag in verwaltetem Code beinhaltet.

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

Dieser Vertragscode kann entweder in der Clientanwendung oder einer anderen Assembly kompiliert werden, die von der Clientanwendung anschließend zum Erstellen eines WCF-Clientobjekts verwendet werden kann. Sie können die Konfigurationsdatei zum Konfigurieren des Clientobjekts verwenden, um eine ordnungsgemäße Verbindung zum Dienst herzustellen.

Ein Beispiel dieses Prozesses finden Sie unter Gewusst wie: Erstellen eines Clients. Weitere Informationen zu Verträgen finden Sie unter Verträge.

Erstellen eines WCF-Clientobjekts

Ein WCF-Client ist ein lokales Objekt, das einen WCF-Dienst in einer Form darstellt, die sich für den Client zum Kommunizieren mit dem Remotedienst eignet. WCF-Clienttypen implementieren den Zieldienstvertrag, sodass Dienstvorgänge nach dem Erstellen und Konfigurieren eines Vertrags direkt mit dem Clientobjekt aufgerufen werden können. Die WCF -Laufzeit konvertiert die Methode Methodenaufrufe in Nachrichten, sendet sie an den Dienst, hört die Antwort und gibt diese Werte in der WCF Clientobjekt als Rückgabewerte oder out oder ref Parameter.

Sie können auch mit WCF-Clientkanalobjekten eine Verbindung zu Diensten herstellen und diese verwenden. Weitere Informationen finden Sie unter WCF-Clientarchitektur.

Erstellen eines neuen WCF-Objekts

Erläutern der Verwendung von einer ClientBase<TChannel> Klasse, nehmen Sie an, die folgende einfache Dienstvertrag von einer dienstanwendung generiert wurde.

Hinweis

Wird zum Erstellen des Visual Studio-Clients WCF verwendet, werden Objekte beim Hinzufügen eines Dienstverweises zum Projekt automatisch in den Objektkatalog geladen.

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

Wenn Sie nicht arbeiten Visual Studio, untersuchen Sie den generierten Vertragscode, um den Typ zu suchen, die erweitert ClientBase<TChannel> und die dienstvertragsschnittstelle ISampleService. In diesem Fall entspricht der Typ dem folgenden 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);
    }
}

Diese Klasse kann als lokales Objekt mithilfe eines der Konstruktoren erstellt, konfiguriert und anschließend zum Herstellen einer Verbindung zu einem Dienst vom Typ ISampleService verwendet werden.

Es wird empfohlen, zuerst das WCF-Clientobjekt zu erstellen, es anschließend zu verwenden und in einem einzelnen try/catch-Block zu schließen. Verwenden Sie nicht die using-Anweisung (Using in Visual Basic), da Ausnahmen in bestimmten Fehlermodi möglicherweise nicht angezeigt werden. Weitere Informationen finden Sie unterden folgenden Abschnitten werden auch als Vermeiden von Problemen mit der Using-Anweisung.

Verträge, Bindungen und Adressen

Bevor ein WCF-Clientobjekt erstellt werden kann, ist eine Konfiguration des Clientobjekts erforderlich. Insbesondere müssen sie einen Dienst Endpunkt verwenden. Ein Endpunkt ist die Kombination eines Dienstvertrags, einer Bindung und einer Adresse. (Weitere Informationen finden Sie unter Endpunkte finden Sie unter Endpunkte: Adressen, Bindungen und Verträge.) In der Regel befindet sich diese Informationen der <> > Element in einer Konfigurationsdatei der Clientanwendung, beispielsweise das Tool "Svcutil.exe" generiert und wird automatisch geladen, wenn Sie Ihre Clientobjekt erstellen. Beide WCF-Clienttypen verfügen auch über Überladungen, die das programmgesteuerte Angeben dieser Informationen ermöglichen.

Beispielsweise beinhaltet eine generierte Konfigurationsdatei für einen in den vorherigen Beispielen verwendeten ISampleService die folgenden Endpunktinformationen.

Mit dieser Konfigurationsdatei wird ein Zielendpunkt im <client>-Element angegeben. Weitere Informationen finden Sie unterVerwenden mehrerer Zielendpunkte finden Sie unter der ClientBase<TChannel>.ClientBase<TChannel> oder ChannelFactory<TChannel>.ChannelFactory<TChannel> Konstruktoren.

Aufrufen von Vorgängen

Erstellen Sie nach dem Erstellen und Konfigurieren eines Clientobjekts einen try/catch-Block, rufen Sie Vorgänge ebenso auf, als handelte es sich um ein lokales Objekt, und schließen Sie das WCF-Clientobjekt. Beim Aufruf des ersten Vorgangs durch die Clientanwendung öffnet WCF automatisch den zugrunde liegenden Kanal. Dieser wird bei Wiederverwendung des Objekts geschlossen. (Es besteht auch die Möglichkeit, den Kanal vor oder nach dem Aufruf anderer Vorgänge explizit zu öffnen und zu schließen.)

Beispiel: Sie verfügen über den folgenden Dienstvertrag:

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  

Sie können Vorgänge durch Erstellen eines WCF-Clientobjekts und durch Aufrufen der Methoden aufrufen (siehe folgendes Beispiel). Das Öffnen, Aufrufen und Schließen des WCF-Clientobjekts erfolgt innerhalb eines einzelnen try/catch-Blocks. Weitere Informationen finden Sie unterZugreifen auf Dienste mithilfe eines WCF-Clients und zur Vermeidung von Problemen mit der Using-Anweisung.

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

Behandeln von Fehlern

Ausnahmen können in einer Clientanwendung unter folgenden Bedingungen auftreten: beim Öffnen des zugrunde liegenden Kanals (entweder explizit oder automatisch durch Aufrufen eines Vorgangs), beim Aufrufen von Vorgängen mit dem Client- oder Kanalobjekt oder beim Schließen des zugrunde liegenden Clientkanals. Es sollten mindestens Applikationen erwarten, behandeln mögliche System.TimeoutException und System.ServiceModel.CommunicationException -Ausnahmen sowie jegliche System.ServiceModel.FaultException Objekte, die infolge von durch Vorgänge zurückgegebenen SOAP-Fehler ausgelöst. Im Vorgangsvertrag angegebene SOAP-Fehler werden ausgelöst, um den Clientanwendungen als eine System.ServiceModel.FaultException<TDetail> , in dem der Typparameter der Detailtyp des SOAP-Fehlers ist. Weitere Informationen finden Sie unterBehandeln von Fehlerzuständen in einer Clientanwendung finden Sie unter senden und Empfangen von Fehlern. Ein vollständiges Beispiel für das Behandeln von Fehlern in einem Client, finden Sie unter Ausnahmen erwartet.

Konfigurieren und Sichern von Clients

Das Konfigurieren eines Clients beginnt mit dem erforderlichen Laden von Zielendpunktinformationen für das Client- oder Kanalobjekt (in der Regel von einer Konfigurationsdatei), obwohl diese Informationen auch programmgesteuert mithilfe der Clientkonstruktoren und -eigenschaften geladen werden können. Allerdings sind zusätzliche Konfigurationsschritte erforderlich, um ein bestimmtes Clientverhalten zu ermöglichen und zahlreichen Sicherheitsszenarien gerecht zu werden.

Beispielsweise werden Sicherheitsanforderungen für Dienstverträge in der Dienstvertragschnittstelle deklariert, und falls mit Svcutil.exe eine Konfigurationsdatei erstellt wurde, beinhaltet diese Datei normalerweise eine Bindung, die den Sicherheitsanforderungen des Diensts entspricht. In einigen Fällen sind jedoch möglicherweise zusätzliche Sicherheitskonfigurationen erforderlich, zum Beispiel die Konfiguration von Clientanmeldeinformationen. Vollständige Informationen zur Konfiguration der Sicherheit für WCF -Clients finden Sie unter Schützen von Clients.

Zudem können einige benutzerdefinierte Änderungen in Clientanwendungen aktiviert werden, zum Beispiel benutzerdefiniertes Laufzeitverhalten. Weitere Informationen finden Sie unterzum Konfigurieren eines benutzerdefinierten Clientverhaltens finden Sie unter Konfigurieren von Clientverhalten.

Erstellen von Rückrufobjekten für Duplexdienste

Mit Duplexdiensten wird ein Rückrufvertrag angegeben, den die Clientanwendung implementieren muss, um gemäß den Vertragsanforderungen ein Rückrufobjekt für den aufzurufenden Dienst bereitzustellen. Obgleich es sich bei Rückrufobjekten nicht um vollständige Dienste handelt (beispielsweise kann ein Kanal nicht mit einem Rückrufobjekt initiiert werden), können Sie zu Implementierungs- und Konfigurationszwecken als eine Art Dienst betrachtet werden.

Clients von Duplexdiensten müssen folgende Vorgänge ausführen:

  • Eine Rückrufvertragsklasse implementieren.

  • Erstellen Sie eine Instanz der Implementierungsklasse des Rückrufs und zur Erstellung der System.ServiceModel.InstanceContext -Objekt, das Sie übergeben den WCF clientkonstruktor.

  • Vorgänge aufrufen und Vorgangsrückrufe behandeln.

Duplex-WCF-Clientobjekte funktionieren wie ihre Gegenstücke ohne Duplex, mit der Einschränkung, dass sie zur Unterstützung von Rückrufen erforderliche Funktionen verfügbar machen (einschließlich der Konfiguration des Rückrufdiensts).

Beispielsweise können Sie verschiedene Aspekte des Laufzeitverhaltens Rückruf steuern, indem Sie mithilfe der Eigenschaften der der System.ServiceModel.CallbackBehaviorAttribute -Attribut für die Rückrufklasse. Ein weiteres Beispiel ist die Verwendung der System.ServiceModel.Description.CallbackDebugBehavior Klasse, um die Rückgabe von Ausnahmeinformationen an Dienste zu ermöglichen, die das Rückrufobjekt aufrufen. Weitere Informationen finden Sie unterDuplexdienste. Ein vollständiges Beispiel finden Sie unter Duplex.

Auf Windows XP-Computern, die mit Internet Information Services (IIS) 5.1, muss von duplexclients eine clientbasisadresse mithilfe der System.ServiceModel.WSDualHttpBinding Klasse oder eine Ausnahme ausgelöst. Im folgenden Codebeispiel wird die entsprechende Umsetzung in Code veranschaulicht.

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

Im folgenden Codebeispiel wird die entsprechende Umsetzung in einer Konfigurationsdatei veranschaulicht.

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

Asynchrones Aufrufen von Diensten

Die Art und Weise eines Vorgangsaufrufs ist ausschließlich Angelegenheit des Cliententwicklers. Dies liegt daran, dass die Nachrichten, aus denen sich ein Vorgang zusammensetzt, bei der Darstellung in verwaltetem Code entweder synchronen oder asynchronen Methoden zugeordnet werden können. Wenn Sie einen Client erstellen möchten, mit dem Vorgänge asynchron aufgerufen werden, können Sie daher mit Svcutil.exe und der Option /async asynchronen Clientcode generieren. Weitere Informationen finden Sie unterGewusst wie: Asynchrones Aufrufen von Dienstvorgängen.

Aufrufen von Diensten mithilfe der WCF-Clientkanäle.

WCF-Clienttypen erweitern ClientBase<TChannel>, die wiederum leitet sich von System.ServiceModel.IClientChannel das zugrunde liegende kanalsystem verfügbar gemacht. Sie können Dienste aufrufen, verwenden Sie den zieldienstvertrag mit der System.ServiceModel.ChannelFactory<TChannel> Klasse. Weitere Informationen finden Sie unter WCF-Clientarchitektur.

Siehe auch

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