Übersicht über den WCF-Client

  • Artikel

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. Normalerweise geschieht dies durch Verwendung des ServiceModel Metadata Utility-Tool (Svcutil.exe) zum Herunterladen von Metadaten vom Dienst, die anschließend in eine verwaltete Quellcodedatei in der gewünschten Sprache konvertiert werden. Anschließend wird eine Konfigurationsdatei für die Clientanwendung erstellt, die zum Konfigurieren des WCF-Clientobjekts verwendet werden kann. 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 für diesen Prozess finden Sie unter Gewusst wie: Erstellen eines Windows Communication Foundation-Clients. 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 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 Methodenaufrufe in Nachrichten, sendet diese anschließend an den Dienst, hört die Antwort ab und gibt diese Werte an das WCF-Clientobjekt als Rückgabewerte oder als out -Parameter bzw. ref-Parameter zurück.

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

Erstellen eines neuen WCF-Objekts

Wenn Sie die Verwendung einer ClientBase-Klasse darstellen möchten, nehmen Sie an, dass der folgende einfache Dienstvertrag von einer Dienstanwendung generiert wurde.

ms735103.note(de-de,VS.100).gifHinweis:
Wird zum Erstellen des WCF-Clients Visual Studio 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);
}

Wird Visual Studio nicht verwendet, prüfen Sie den generierten Vertragscode, um den Typ zu suchen, durch den ClientBase und die Dienstvertragsschnittstelle ISampleService erweitert werden. 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 unter Vermeiden von Problemen mit der Using-Anweisung sowie in den folgenden Abschnitten:

Verträge, Bindungen und Adressen

Bevor ein WCF-Clientobjekt erstellt werden kann, ist eine Konfiguration des Clientobjekts erforderlich. Das Objekt benötigt insbesondere einen verwendbaren Dienstendpunkt. Ein Endpunkt ist die Kombination eines Dienstvertrags, einer Bindung und einer Adresse. (Weitere Informationen über zu Endpunkten finden Sie unter Endpunkte: Adressen, Bindungen und Verträge.) Normalerweise befinden sich diese Informationen im <endpoint>-Element in der Konfigurationsdatei einer Clientanwendung (beispielsweise die vom Tool Svcutil.exe generierte Konfigurationsdatei), und sie werden beim Erstellen des Clientobjekts automatisch geladen. 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.

<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="https://localhost:8080/SampleService" binding="wsHttpBinding"
                bindingConfiguration="WSHttpBinding_ISampleService" contract="ISampleService"
                name="WSHttpBinding_ISampleService">
            </endpoint>
        </client>
    </system.serviceModel>
</configuration>

Mit dieser Konfigurationsdatei wird ein Zielendpunkt im <client>-Element angegeben. Weitere Informationen über zum Verwenden mehrerer Zielendpunkte finden Sie im System.ServiceModel.ClientBase.#ctor(System.String)-Konstruktor oder im System.ServiceModel.ChannelFactory.#ctor(System.String)-Konstruktor.

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 vollzieht sich innerhalb eines einzelnen try/catch-Blocks. Weitere Informationen finden Sie unter Zugreifen auf Dienste mithilfe eines Clients und unter Vermeiden 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. 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 zu Clientanwendungen heraufgestuft, wobei der Typparameter der Detailtyp des SOAP-Fehlers ist. Weitere Informationen über zum Behandeln von Fehlerbedingungen 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 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 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 Sichern von Clients.

Zudem können einige benutzerdefinierte Änderungen in Clientanwendungen aktiviert werden, wie zum Beispiel benutzerdefinierte Laufzeitverhalten. Weitere Informationen über zum 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.

  • Eine Instanz der Implementierungsklasse des Rückrufvertrags erstellen und diese zum Erstellen des System.ServiceModel.InstanceContext-Objekts verwenden, das an den WCF-Clientkonstruktor übergeben wird.

  • 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 verschiedene Aspekte des Laufzeitverhaltens des Rückrufobjekts mithilfe der Eigenschaften des System.ServiceModel.CallbackBehaviorAttribute-Attributs in der Rückrufklasse gesteuert werden. Ein weiteres Beispiel ist die Verwendung der System.ServiceModel.Description.CallbackDebugBehavior-Klasse, um die Rückgabe von Ausnahmeinformationen an Dienste, die das Rückrufobjekt aufrufen, zu ermöglichen. 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, muss von Duplexclients eine Clientbasisadresse mithilfe der System.ServiceModel.WSDualHttpBinding-Klasse angegeben werden, da andernfalls eine Ausnahme ausgelöst wird. Im folgenden Codebeispiel wird die entsprechende Umsetzung in Code veranschaulicht.

Dim dualBinding As New WSDualHttpBinding()
Dim endptadr As New EndpointAddress("https://localhost:12000/DuplexTestUsingCode/Server")
dualBinding.ClientBaseAddress = New Uri("https://localhost:8000/DuplexTestUsingCode/Client/")

WSDualHttpBinding dualBinding = new WSDualHttpBinding();
EndpointAddress endptadr = new EndpointAddress("https://localhost:12000/DuplexTestUsingCode/Server");
dualBinding.ClientBaseAddress = new Uri("https://localhost:8000/DuplexTestUsingCode/Client/");

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

'      <client>
'        <endpoint 
'          name ="ServerEndpoint" 
'          address="https://localhost:12000/DuplexUsingConfig/Server"
'          bindingConfiguration="WSDualHttpBinding_IDuplex" 
'          binding="wsDualHttpBinding"
'          contract="IDuplex" 
'      />
'      </client>
'      <bindings>
'        <wsDualHttpBinding>
'          <binding 
'            name="WSDualHttpBinding_IDuplex"  
'            clientBaseAddress="https://localhost:8000/myClient/" 
'          />
'        </wsDualHttpBinding>
'      </bindings>

<client>
  <endpoint 
    name ="ServerEndpoint" 
    address="https://localhost:12000/DuplexUsingConfig/Server"
    bindingConfiguration="WSDualHttpBinding_IDuplex" 
    binding="wsDualHttpBinding"
    contract="IDuplex" 
/>
</client>
<bindings>
  <wsDualHttpBinding>
    <binding 
      name="WSDualHttpBinding_IDuplex"  
      clientBaseAddress="https://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 unter Vorgehensweise: Asynchrones Aufrufen von WCF-Dienstvorgängen.

Aufrufen von Diensten mithilfe der WCF-Clientkanäle.

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

Siehe auch

Verweis

System.ServiceModel.ClientBase
System.ServiceModel.ChannelFactory