Zugreifen auf Dienste mithilfe eines WCF-ClientsAccessing Services Using a WCF Client

Nachdem Sie einen Dienst erstellt haben, besteht der nächste Schritt erstellen Sie einen WCF-Clientproxy.After you create a service, the next step is to create a WCF client proxy. Eine Clientanwendung verwendet den WCF-Clientproxy, um mit dem Dienst kommunizieren.A client application uses the WCF client proxy to communicate with the service. Clientanwendungen importieren normalerweise Metadaten eines Diensts, um WCF-Clientcode generieren, die zum Aufrufen des Diensts verwendet werden kann.Client applications usually import a service's metadata to generate WCF client code that can be used to invoke the service.

Die grundlegenden Schritte zum Erstellen eines WCF-Clients umfassen Folgendes:The basic steps for creating a WCF client include the following:

  1. Kompilieren Sie den Dienstcode.Compile the service code.

  2. Generieren Sie den WCF-Clientproxy.Generate the WCF client proxy.

  3. Instanziieren Sie den WCF-Clientproxy.Instantiate the WCF client proxy.

Der WCF-Clientproxy kann manuell generiert werden, mithilfe der Service Model Metadata Utility Tool (SvcUtil.exe) Weitere Informationen finden Sie unter ServiceModel Metadata Utility Tool (Svcutil.exe).The WCF client proxy can be generated manually by using the Service Model Metadata Utility Tool (SvcUtil.exe) for more information see, ServiceModel Metadata Utility Tool (Svcutil.exe). Der WCF-Clientproxy kann auch mithilfe der Funktion Dienstverweis hinzufügen in Visual Studio generiert werden.The WCF client proxy can also be generated within Visual Studio using the Add Service Reference feature. Um den WCF-Clientproxy mithilfe einer dieser Methoden zu generieren, muss der Dienst ausgeführt werden.To generate the WCF client proxy using either method the service must be running. Wenn es sich um einen selbst gehosteten Dienst handelt, müssen Sie den Host ausführen.If the service is self-hosted you must run the host. Wenn der Dienst in IIS/WAS gehostet wird, ist kein weiterer Schritt erforderlich.If the service is hosted in IIS/WAS you do not need to do anything else.

ServiceModel Metadata Utility ToolServiceModel Metadata Utility Tool

Die ServiceModel Metadata Utility Tool (Svcutil.exe) ist ein Befehlszeilentool zum Generieren von Code aus den Metadaten.The ServiceModel Metadata Utility Tool (Svcutil.exe) is a command-line tool for generating code from metadata. Die folgende Verwendung ist ein Beispiel für einen grundlegenden Svcutil.exe-Befehl.The following use is an example of a basic Svcutil.exe command.

Svcutil.exe <service's Metadata Exchange (MEX) address or HTTP GET address>   

Alternativ können Sie Svcutil.exe mit WSDL (Web Services Description Language) und XSD (XML Schema Definition Language)-Dateien im Dateisystem verwenden.Alternatively, you can use Svcutil.exe with Web Services Description Language (WSDL) and XML Schema definition language (XSD) files on the file system.

Svcutil.exe <list of WSDL and XSD files on file system>  

Das Ergebnis ist eine Codedatei, die WCF-Clientcode, die die Clientanwendung verwenden können enthält, um den Dienst aufzurufen.The result is a code file that contains WCF client code that the client application can use to invoke the service.

Sie können das Tool auch zum Generieren von Konfigurationsdateien verwenden.You can also use the tool to generate configuration files.

Svcutil.exe <file1 [,file2]>  

Wenn nur ein Dateiname angegeben wird, ist das der Name der Ausgabedatei.If only one file name is given, that is the name of the output file. Wenn zwei Dateinamen angegeben werden, ist die erste Datei eine Eingabekonfigurationsdatei, deren Inhalt mit der generierten Konfiguration zusammengeführt und in die zweite Datei geschrieben wird.If two file names are given, then the first file is an input configuration file whose contents are merged with the generated configuration and written out into the second file. Weitere Informationen zur Konfiguration finden Sie unter Konfigurieren von Bindungen für Dienste.For more information about configuration, see Configuring Bindings for Services.

Wichtig

Nicht gesicherte Metadatenanforderungen stellen genau wie nicht gesicherte Netzwerkanforderungen ein gewisses Risiko dar: Wenn Sie sich nicht sicher sind, ob der Endpunkt, mit dem Sie kommunizieren, der vorgegebenen Identität entspricht, stammen die abgerufenen Informationen unter Umständen von einem bösartigen Dienst.Unsecured metadata requests pose certain risks in the same way that any unsecured network request does: If you are not certain that the endpoint you are communicating with is who it says it is, the information you retrieve might be metadata from a malicious service.

"Dienstverweis hinzufügen" in Visual StudioAdd Service Reference in Visual Studio

Mit dem Dienst wird ausgeführt, mit der rechten Maustaste klicken Sie auf das Projekt, das den WCF-Clientproxy enthalten wird, und wählen Hinzufügen eines Dienstverweises.With the service running, right click the project that will contain the WCF client proxy and select Add Service Reference. In der hinzufügen "Dienstverweis" Geben Sie die URL des Diensts, die Sie verwenden möchten, rufen Sie aus, und klicken Sie auf die Go Schaltfläche.In the Add Service Reference Dialog type in the URL to the service you want to call and click the Go button. Das Dialogfeld zeigt eine Liste der Dienste an, die unter der Adresse verfügbar sind.The dialog will display a list of services available at the address you specify. Klicken Sie mit der Doppelklicken auf den Dienst finden Sie unter die Verträge und Vorgänge verfügbar, geben Sie einen Namespace für den generierten Code aus, und klicken Sie auf die OK Schaltfläche.Double click the service to see the contracts and operations available, specify a namespace for the generated code and click the OK button.

BeispielExample

Im folgenden Codebeispiel wird ein für einen Dienst erstellter Dienstvertrag gezeigt.The following code example shows a service contract created for a service.

// Define a service contract.
[ServiceContract(Namespace="http://Microsoft.ServiceModel.Samples")]
public interface ICalculator
{
    [OperationContract]
    double Add(double n1, double n2);
    // Other methods are not shown here.
}
' Define a service contract.
<ServiceContract(Namespace:="http://Microsoft.ServiceModel.Samples")> _
Public Interface ICalculator
    <OperationContract()>  _
    Function Add(ByVal n1 As Double, ByVal n2 As Double) As Double
    ' Other methods are not shown here.
End Interface

Das ServiceModel Metadata Utility-Tool und Hinzufügen eines Dienstverweises in Visual Studio generiert die folgenden WCF-Clientklasse.The ServiceModel Metadata utility tool and Add Service Reference in Visual Studio generates the following WCF client class. Die Klasse erbt von der generischen ClientBase<TChannel>-Klasse und implementiert die ICalculator-Schnittstelle.The class inherits from the generic ClientBase<TChannel> class and implements the ICalculator interface. Das Tool generiert auch die ICalculator-Schnittstelle (wird hier nicht gezeigt).The tool also generates the ICalculator interface (not shown here).

public partial class CalculatorClient : System.ServiceModel.ClientBase<ICalculator>, ICalculator
{
    public CalculatorClient()
    {}

    public CalculatorClient(string endpointConfigurationName) :
            base(endpointConfigurationName)
    {}

    public CalculatorClient(string endpointConfigurationName, string remoteAddress) :
            base(endpointConfigurationName, remoteAddress)
    {}

    public CalculatorClient(string endpointConfigurationName,
        System.ServiceModel.EndpointAddress remoteAddress) :
            base(endpointConfigurationName, remoteAddress)
    {}

    public CalculatorClient(System.ServiceModel.Channels.Binding binding,
        System.ServiceModel.EndpointAddress remoteAddress) :
            base(binding, remoteAddress)
    {}

    public double Add(double n1, double n2)
    {
        return base.Channel.Add(n1, n2);
    }
}
Partial Public Class CalculatorClient
    Inherits System.ServiceModel.ClientBase(Of ICalculator)
    Implements ICalculator

    Public Sub New()
        MyBase.New
    End Sub

    Public Sub New(ByVal endpointConfigurationName As String)
        MyBase.New(endpointConfigurationName)
    End Sub

    Public Sub New(ByVal endpointConfigurationName As String, ByVal remoteAddress As String)
        MyBase.New(endpointConfigurationName, remoteAddress)
    End Sub

    Public Sub New(ByVal endpointConfigurationName As String,
        ByVal remoteAddress As System.ServiceModel.EndpointAddress)
        MyBase.New(endpointConfigurationName, remoteAddress)
    End Sub

    Public Sub New(ByVal binding As System.ServiceModel.Channels.Binding,
        ByVal remoteAddress As System.ServiceModel.EndpointAddress)
        MyBase.New(binding, remoteAddress)
    End Sub

    Public Function Add(ByVal n1 As Double, ByVal n2 As Double) As Double
        Implements ICalculator.Add
        Return MyBase.Channel.Add(n1, n2)
    End Function
End Class

Verwenden des WCF-ClientsUsing the WCF Client

Um den WCF-Client verwenden, erstellen Sie eine Instanz der WCF-Client, und rufen Sie klicken Sie dann seine Methoden auf, wie im folgenden Code gezeigt.To use the WCF client, create an instance of the WCF client, and then call its methods, as shown in the following code.

// Create a client object with the given client endpoint configuration.
CalculatorClient calcClient = new CalculatorClient("CalculatorEndpoint"));
// Call the Add service operation.
double value1 = 100.00D;
double value2 = 15.99D;
double result = calcClient.Add(value1, value2);
Console.WriteLine("Add({0},{1}) = {2}", value1, value2, result);
' Create a client object with the given client endpoint configuration.
Dim calcClient As CalculatorClient = _
New CalculatorClient("CalculatorEndpoint")

' Call the Add service operation.
Dim value1 As Double = 100.00D
Dim value2 As Double = 15.99D
Dim result As Double = calcClient.Add(value1, value2)
Console.WriteLine("Add({0},{1}) = {2}", value1, value2, result)

Debuggen der von einem Client ausgelösten AusnahmenDebugging Exceptions Thrown by a Client

Viele von einem WCF-Client ausgelöste Ausnahmen werden durch eine Ausnahme für den Dienst verursacht.Many exceptions thrown by a WCF client are caused by an exception on the service. Im Folgenden finden Sie einige Beispiele:Some examples of this are:

  • SocketException: Vom Remotehost wurde die Schließung einer bestehenden Verbindung erzwungen.SocketException: An existing connection was forcibly closed by the remote host.

  • CommunicationException: Die zugrunde liegende Verbindung wurde unerwartet geschlossen.CommunicationException: The underlying connection was closed unexpectedly.

  • CommunicationObjectAbortedException: Die Socketverbindung wurde abgebrochen.CommunicationObjectAbortedException: The socket connection was aborted. Mögliche Ursache: Ein Fehler beim Verarbeiten der Nachricht, eine Zeitüberschreitung durch den Remotehost beim Empfang oder ein Problem mit einer zugrunde liegenden Netzwerkressource.This could be caused by an error processing your message, a receive time-out being exceeded by the remote host, or an underlying network resource issue.

Tritt eine Ausnahme dieses Typs auf, aktivieren Sie die Ablaufverfolgung auf der Dienstseite, und ermitteln Sie die dort aufgetretene Ausnahme.When these types of exceptions occur, the best way to solve the problem is to turn on tracing on the service side and determine what exception occurred there. Weitere Informationen zur Ablaufverfolgung finden Sie unter Ablaufverfolgung und mithilfe-Ablaufverfolgung zum Beheben der Anwendung.For more information about tracing, see Tracing and Using Tracing to Troubleshoot Your Application.

Siehe auchSee Also

Vorgehensweise: Erstellen eines ClientsHow to: Create a Client
Vorgehensweise: Zugreifen auf Dienste mit einem DuplexvertragHow to: Access Services with a Duplex Contract
Vorgehensweise: Asynchrones Aufrufen von DienstvorgängenHow to: Call Service Operations Asynchronously
Vorgehensweise: Zugreifen auf Dienste mit unidirektionalen und Anforderung-Antwort-VerträgenHow to: Access Services with One-Way and Request-Reply Contracts
Vorgehensweise: Zugriff auf einen WSE3.0-DienstHow to: Access a WSE 3.0 Service
Grundlagen des generierten ClientcodesUnderstanding Generated Client Code
Vorgehensweise: Verbessern der Startzeit von WCF-Clientanwendungen mit dem XmlSerializerHow to: Improve the Startup Time of WCF Client Applications using the XmlSerializer
Angeben des ClientlaufzeitverhaltensSpecifying Client Run-Time Behavior
Konfigurieren von ClientverhaltenConfiguring Client Behaviors