Freigeben über

ÜBERSICHT ÜBER DEN WCF-Client

In diesem Abschnitt wird beschrieben, was Clientanwendungen tun, wie Sie einen Windows Communication Foundation (WCF)-Client konfigurieren, erstellen und verwenden und wie Sie Clientanwendungen sichern.

Verwenden von WCF-Clientobjekten

Eine Clientanwendung ist eine verwaltete Anwendung, die einen WCF-Client für die Kommunikation mit einer anderen Anwendung verwendet. Zum Erstellen einer Clientanwendung für einen WCF-Dienst sind die folgenden Schritte erforderlich:

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

  2. Erstellen Sie einen WCF-Client mithilfe dieser Informationen.

  3. Anrufvorgänge.

  4. Schließen Sie das WCF-Clientobjekt.

In den folgenden Abschnitten werden diese Schritte erläutert und kurze Einführungen zu den folgenden Problemen bereitgestellt:

  • Behandeln von Fehlern

  • Konfigurieren und Sichern von Clients.

  • Erstellen von Rückrufobjekten für Duplexdienste

  • Das asynchrone Aufrufen von Diensten.

  • Aufrufen von Diensten mithilfe von Clientkanälen.

Abrufen von Dienstvertrag, Bindungen und Adressen

In WCF modellieren Dienste und Clients Verträge mit verwalteten Attributen, Schnittstellen und Methoden. Um eine Verbindung mit einem Dienst in einer Clientanwendung herzustellen, müssen Sie die Typinformationen für den Servicevertrag abrufen. In der Regel erhalten Sie Typinformationen für den Dienstvertrag mithilfe des ServiceModel Metadata Utility Tools (Svcutil.exe). Das Hilfsprogramm lädt Metadaten vom Dienst herunter, konvertiert sie in eine verwaltete Quellcodedatei in der von Ihnen gewählten Sprache und erstellt eine Clientanwendungskonfigurationsdatei, die Sie zum Konfigurieren des WCF-Clientobjekts verwenden können. Wenn Sie z. B. ein WCF-Clientobjekt erstellen, um ein MyCalculatorService aufzurufen, und Sie wissen, dass die Metadaten für diesen Dienst unter http://computerName/MyCalculatorService/Service.svc?wsdl veröffentlicht werden, zeigt das folgende Code-Beispiel, wie Sie Svcutil.exe verwenden, um eine ClientCode.vb-Datei abzurufen, die den Dienstvertrag in verwaltetem Code enthält.

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

Sie können diesen Vertragscode entweder in der Clientanwendung oder in einer anderen Assembly kompilieren, mit der die Clientanwendung dann ein WCF-Clientobjekt erstellen kann. Sie können die Konfigurationsdatei verwenden, um das Clientobjekt so zu konfigurieren, dass eine ordnungsgemäße Verbindung mit dem Dienst hergestellt wird.

Ein Beispiel für diesen Prozess finden Sie unter How to: Create a Client. Ausführlichere 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 einem Formular darstellt, mit dem der Client mit dem Remotedienst kommunizieren kann. WCF-Clienttypen implementieren den Zieldienstvertrag. Wenn Sie einen erstellen und konfigurieren, können Sie das Clientobjekt dann direkt zum Aufrufen von Dienstvorgängen verwenden. Die WCF-Laufzeit konvertiert die Methodenaufrufe in Nachrichten, sendet sie an den Dienst, überwacht die Antwort und gibt diese Werte als Rückgabewerte oder outref Parameter an das WCF-Clientobjekt zurück.

Sie können auch WCF-Clientkanalobjekte verwenden, um eine Verbindung mit Diensten herzustellen und diese zu verwenden. Ausführliche Informationen finden Sie unter WCF-Clientarchitektur.

Erstellen eines neuen WCF-Objekts

Um die Verwendung einer ClientBase<TChannel> Klasse zu veranschaulichen, gehen Sie davon aus, dass der folgende einfache Dienstvertrag aus einer Dienstanwendung generiert wurde.

Hinweis

Wenn Sie Visual Studio zum Erstellen des WCF-Clients verwenden, werden Objekte automatisch in den Objektbrowser geladen, wenn Sie ihrem Projekt einen Dienstverweis hinzufügen.

[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 Visual Studio nicht verwenden, überprüfen Sie den generierten Vertragscode, um den Typ zu finden, der ClientBase<TChannel> erweitert, und die Dienstvertragsschnittstelle ISampleService ausfindig zu machen. In diesem Fall sieht dieser Typ wie der folgende Code aus:

[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 dann zum Herstellen einer Verbindung mit einem Dienst des Typs ISampleServiceverwendet 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 die using Anweisung (Using in Visual Basic) nicht, da sie Ausnahmen in bestimmten Fehlermodi maskieren kann. Weitere Informationen finden Sie in den folgenden Abschnitten sowie unter Schließen und Abbrechen zum Freigeben von WCF-Clientressourcen.

Verträge, Bindungen und Adressen

Bevor Sie ein WCF-Clientobjekt erstellen können, müssen Sie das Clientobjekt konfigurieren. Das Objekt benötigt insbesondere einen verwendbaren Dienstendpunkt. Ein Endpunkt ist die Kombination aus einem Dienstvertrag, einer Bindung und einer Adresse. (Weitere Informationen zu Endpunkten finden Sie unter Endpunkte: Adressen, Bindungen und Verträge.) Diese Informationen befinden sich im <Endpunkten>-Element einer Konfigurationsdatei der Clientanwendung, wie sie z. B. vom Svcutil.exe-Tool generiert wird, und werden automatisch geladen, wenn Sie Ihr Clientobjekt erstellen. Beide WCF-Clienttypen verfügen auch über Überladungen, mit denen Sie diese Informationen programmgesteuert angeben können.

Beispielsweise enthält eine für ein in den vorherigen Beispielen verwendetes ISampleService generierte Konfigurationsdatei die folgenden Endpunktinformationen.

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

Diese Konfigurationsdatei gibt einen Zielendpunkt im <client> Element an. Weitere Informationen zur Verwendung mehrerer Zielendpunkte finden Sie in den Konstruktoren ClientBase<TChannel> oder ChannelFactory<TChannel>.

Anrufvorgänge

Nachdem Sie ein Clientobjekt erstellt und konfiguriert haben, erstellen Sie einen Try/Catch-Block, rufen Sie Vorgänge auf die gleiche Weise auf, wie das Objekt lokal wäre, und schließen Sie das WCF-Clientobjekt. Wenn die Clientanwendung den ersten Vorgang aufruft, öffnet WCF automatisch den zugrunde liegenden Kanal, und der zugrunde liegende Kanal wird geschlossen, wenn das Objekt wiederverwendet wird. (Alternativ können Sie den Kanal vor oder nach dem Aufrufen anderer Vorgänge explizit öffnen und schließen.)

Wenn Sie beispielsweise über den folgenden Servicevertrag verfügen:

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 aufrufen, indem Sie ein WCF-Clientobjekt erstellen und seine Methoden aufrufen, wie im folgenden Codebeispiel veranschaulicht. Das Öffnen, Aufrufen und Schließen des WCF-Clientobjekts erfolgt innerhalb eines einzelnen Try/Catch-Blocks. Weitere Informationen finden Sie unter "Zugreifen auf Dienste mithilfe eines WCF-Clients " und "Schließen und Abbrechen", um WCF-Clientressourcen freizugeben.

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 auftreten, wenn der zugrunde liegende Clientkanal geöffnet wird, sei es explizit oder automatisch durch das Ausführen eines Vorgangs, beim Verwenden des Client- oder Kanalobjekts zum Aufrufen von Vorgängen oder beim Schließen des zugrunde liegenden Clientkanals. Anwendungen sollten zumindest erwarten, mögliche System.TimeoutException-Ausnahmen und System.ServiceModel.CommunicationException-Ausnahmen sowie jegliche System.ServiceModel.FaultException-Objekte zu behandeln, die infolge von durch Vorgänge zurückgegebenen SOAP-Fehlern ausgelöst werden. Im Vorgangsvertrag angegebene SOAP-Fehler werden als System.ServiceModel.FaultException<TDetail> zu Clientanwendungen heraufgestuft, wobei der Typparameter der Detailtyp des SOAP-Fehlers ist. Weitere Informationen zur Behandlung von Fehlerbedingungen in einer Clientanwendung finden Sie unter Senden und Empfangen von Fehlern. Ein vollständiges Beispiel zeigt, wie Fehler in einem Client behandelt werden, finden Sie unter "Erwartete Ausnahmen".

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 aus einer Konfigurationsdatei, obwohl Sie diese Informationen auch programmgesteuert mithilfe der Clientkonstruktoren und -eigenschaften laden können. Zusätzliche Konfigurationsschritte sind jedoch erforderlich, um bestimmtes Clientverhalten und für viele Sicherheitsszenarien zu aktivieren.

Beispielsweise werden Sicherheitsanforderungen für Serviceverträge in der Dienstvertragsschnittstelle deklariert, und wenn Svcutil.exe eine Konfigurationsdatei erstellt haben, enthält diese Datei in der Regel eine Bindung, die die Sicherheitsanforderungen des Diensts unterstützen kann. In einigen Fällen sind jedoch möglicherweise mehr Sicherheitskonfigurationen erforderlich, z. B. das Konfigurieren von Clientanmeldeinformationen. Vollständige Informationen zur Konfiguration der Sicherheit für WCF-Clients finden Sie unter Sichern von Clients.

Darüber hinaus können einige benutzerdefinierte Änderungen in Clientanwendungen aktiviert werden, z. B. benutzerdefinierte Laufzeitverhalten. Weitere Informationen zum Konfigurieren eines benutzerdefinierten Clientverhaltens finden Sie unter Konfigurieren von Clientverhalten.

Erstellen von Rückrufobjekten für Duplexdienste

Duplexdienste geben einen Rückrufvertrag an, den die Clientanwendung implementieren muss, um ein Rückrufobjekt für den Dienst bereitzustellen, der gemäß den Anforderungen des Vertrags aufgerufen werden soll. Obwohl Rückrufobjekte keine vollständigen Dienste sind (z. B. können Sie einen Kanal nicht mit einem Rückrufobjekt initiieren), für die Zwecke der Implementierung und Konfiguration können sie als eine Art Dienst betrachtet werden.

Kunden von Duplexdiensten müssen:

  • Eine Rückrufvertragsklasse implementieren.

  • Erstellen Sie eine Instanz der Rückrufvertragsimplementierungsklasse und verwenden Sie sie, um das System.ServiceModel.InstanceContext Objekt zu erstellen, das Sie an den WCF-Clientkonstruktor übergeben.

  • Vorgänge aufrufen und Vorgangsrückrufe behandeln

Duplex-WCF-Clientobjekte funktionieren wie ihre nichtduplexen Gegenstücke, mit der Ausnahme, dass sie die funktionalität verfügbar machen, die erforderlich ist, um Rückrufe zu unterstützen, einschließlich der Konfiguration des Rückrufdiensts.

Sie können beispielsweise verschiedene Aspekte des Laufzeitverhaltens von Rückrufobjekten steuern, indem Sie Eigenschaften des System.ServiceModel.CallbackBehaviorAttribute Attributs für die Rückrufklasse verwenden. Ein weiteres Beispiel ist die Verwendung der System.ServiceModel.Description.CallbackDebugBehavior Klasse, um die Rückgabe von Ausnahmeinformationen an Dienste zu aktivieren, die das Rückrufobjekt aufrufen. Weitere Informationen finden Sie unter Duplexdienste. Ein vollständiges Beispiel finden Sie unter Duplex.

Auf Windows XP-Computern, auf denen Internetinformationsdienste (IIS) 5.1 ausgeführt wird, müssen Duplexclients eine Clientbasisadresse angeben, die die System.ServiceModel.WSDualHttpBinding Klasse verwendet oder eine Ausnahme ausgelöst wird. Im folgenden Codebeispiel wird gezeigt, wie dies im Code ausgeführt wird.

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

Der folgende Code zeigt, wie dies in einer Konfigurationsdatei ausgeführt wird.

<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 ein Vorgang besteht, entweder synchronen oder asynchronen Methoden zugeordnet werden können, wenn sie in verwaltetem Code ausgedrückt werden. Wenn Sie daher einen Client erstellen möchten, der Vorgänge asynchron aufruft, können Sie Svcutil.exe verwenden, um asynchronen Clientcode mithilfe der /async Option zu generieren. Weitere Informationen finden Sie unter Gewusst wie: Asynchrones Aufrufen von Dienstvorgängen.

Aufrufen von Diensten mithilfe von WCF-Clientkanälen

WCF-Clienttypen erweitern ClientBase<TChannel>, die wiederum von der System.ServiceModel.IClientChannel-Schnittstelle abgeleitet wird, um das zugrunde liegende Kanalsystem verfügbar zu machen. Sie können Dienste mithilfe des Zieldienstvertrags mit der System.ServiceModel.ChannelFactory<TChannel> Klasse aufrufen. Ausführliche Informationen finden Sie unter WCF-Clientarchitektur.

Siehe auch