Panoramica dei client WCFWCF Client Overview

Questa sezione descrive come proteggere le applicazioni client, come configurare, creare e usare un client Windows Communication Foundation (WCF) e cosa fare delle applicazioni client.This section describes what client applications do, how to configure, create, and use a Windows Communication Foundation (WCF) client, and how to secure client applications.

Uso di oggetti client WCFUsing WCF Client Objects

Un'applicazione client è un'applicazione gestita che usa un client WCF per comunicare con un'altra applicazione.A client application is a managed application that uses a WCF client to communicate with another application. Per creare un client dell'applicazione per un servizio WCF sono necessari i passaggi seguenti:To create a client application for a WCF service requires the following steps:

  1. Ottenere le informazioni relative al contratto di servizio, alle associazioni e all'indirizzo per un endpoint di servizio.Obtain the service contract, bindings, and address information for a service endpoint.

  2. Creare un client WCF che utilizza tali informazioni.Create a WCF client using that information.

  3. Chiamare le operazioni.Call operations.

  4. Chiudere l'oggetto client WCF.Close the WCF client object.

Nelle sezioni seguenti vengono illustrate queste procedure e vengono fornite informazioni introduttive sugli argomenti seguenti:The following sections discuss these steps and provide brief introductions to the following issues:

  • Gestione degli errori.Handling errors.

  • Configurazione e protezione dei client.Configuring and securing clients.

  • Creazione di oggetti di callback per i servizi duplex.Creating callback objects for duplex services.

  • Chiamate ai servizi in modo asincrono.Calling services asynchronously.

  • Chiamate ai servizi mediante canali client.Calling services using client channels.

Ottenere informazioni sul contratto di servizio, sulle associazioni e sugli indirizziObtain the Service Contract, Bindings, and Addresses

In WCF, servizi e client modellano i contratti usando attributi gestiti, interfacce e metodi.In WCF, services and clients model contracts using managed attributes, interfaces, and methods. Per eseguire la connessione a un servizio in un'applicazione client è necessario ottenere le informazioni sul tipo per il contratto di servizio.To connect to a service in a client application, you need to obtain the type information for the service contract. In genere, è possibile utilizzando il ServiceModel Metadata Utility Tool (Svcutil.exe), che consente di scaricare i metadati dal servizio, lo converte in un file di codice sorgente gestito nel linguaggio di propria scelta e crea un client file di configurazione dell'applicazione che è possibile usare per configurare l'oggetto client WCF.Typically, you do this by using the ServiceModel Metadata Utility Tool (Svcutil.exe), which downloads metadata from the service, converts it to a managed source code file in the language of your choice, and creates a client application configuration file that you can use to configure your WCF client object. Ad esempio, se si intende creare un oggetto client WCF per richiamare una MyCalculatorService, e si è certi che i metadati per il servizio sia pubblicato nel http://computerName/MyCalculatorService/Service.svc?wsdl, quindi il codice seguente viene illustrato come utilizzare Svcutil.exe per ottenere un ClientCode.vb file contiene il contratto di servizio nel codice gestito.For example, if you are going to create an WCF client object to invoke a MyCalculatorService, and you know that the metadata for that service is published at http://computerName/MyCalculatorService/Service.svc?wsdl, then the following code example shows how to use Svcutil.exe to obtain a ClientCode.vb file that contains the service contract in managed code.

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

È possibile compilare questo codice del contratto nell'applicazione client o in un altro assembly a cui l'applicazione client può quindi usare per creare un oggetto client WCF.You can either compile this contract code into the client application or into another assembly that the client application can then use to create an WCF client object. Per configurare l'oggetto client per eseguire la connessione al servizio in modo appropriato, è possibile usare il file di configurazione.You can use the configuration file to configure the client object to properly connect to the service .

Per un esempio di questo processo, vedere come: Creare un Client.For an example of this process, see How to: Create a Client. Per informazioni più complete sui contratti, vedere contratti.For more complete information about contracts, see Contracts.

Creare un oggetto client WCFCreate a WCF Client Object

Un client WCF è un oggetto locale che rappresenta un servizio WCF in un form che il client può utilizzare per comunicare con il servizio remoto.A WCF client is a local object that represents a WCF service in a form that the client can use to communicate with the remote service. Tipi di client WCF implementano il servizio di destinazione del contratto, quindi quando si crea uno e configurarla, è quindi possibile usare l'oggetto client direttamente per richiamare operazioni del servizio.WCF client types implement the target service contract, so when you create one and configure it, you can then use the client object directly to invoke service operations. Runtime WCF converte le chiamate al metodo in messaggi, li invia al servizio, è in attesa di risposta e restituisce questi valori per l'oggetto client WCF come valori restituiti o out o ref parametri.The WCF run time converts the method calls into messages, sends them to the service, listens for the reply, and returns those values to the WCF client object as return values or out or ref parameters.

È anche possibile utilizzare oggetti canale client WCF per connettersi e utilizzare i servizi.You can also use WCF client channel objects to connect with and use services. Per informazioni dettagliate, vedere architettura Client WCF.For details, see WCF Client Architecture.

Creazione di un nuovo oggetto WCFCreating a New WCF Object

Per illustrare l'uso di una classe ClientBase<TChannel>, si supponga che il contratto di servizio seguente sia stato generato da un'applicazione di servizio.To illustrate the use of a ClientBase<TChannel> class, assume the following simple service contract has been generated from a service application.

Nota

Se si usa Visual Studio crea un client WCF, gli oggetti vengono caricati automaticamente nel Visualizzatore oggetti quando si aggiunge un riferimento al servizio al progetto.If you are using Visual Studio to create your WCF client, objects are loaded automatically into the object browser when you add a service reference to your project.

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

Se non si usa Visual Studio, esaminare il codice del contratto generato per trovare il tipo che estende ClientBase<TChannel> e l'interfaccia del contratto di servizio ISampleService.If you are not using Visual Studio, examine the generated contract code to find the type that extends ClientBase<TChannel> and the service contract interface ISampleService. In questo caso il tipo ha l'aspetto del codice seguente:In this case, that type looks like the following 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);
    }
}

Questa classe può essere creata come un oggetto locale usando uno dei costruttori, configurata e quindi usata per la connessione a un servizio del tipo ISampleService.This class can be created as a local object using one of the constructors, configured, and then used to connect to a service of the type ISampleService.

È consigliabile creare prima di tutto l'oggetto client WCF e quindi usarla e chiuderla all'interno di un blocco try/catch singolo.It is recommended that you create your WCF client object first, and then use it and close it inside a single try/catch block. È consigliabile non usare la using istruzione (Using in Visual Basic) in quanto potrebbe mascherare eccezioni in determinate modalità di errore.You should not use the using statement (Using in Visual Basic) because it may mask exceptions in certain failure modes. Per altre informazioni, vedere le sezioni seguenti nonché utilizzare Chiudi e Interrompi per rilasciare le risorse del client WCF.For more information, see the following sections as well as Use Close and Abort to release WCF client resources.

Contratti, associazioni e indirizzi.Contracts, Bindings, and Addresses

Prima di creare un oggetto client WCF, è necessario configurare l'oggetto client.Before you can create a WCF client object, you must configure the client object. In particolare, deve avere un servizio endpoint da usare.Specifically, it must have a service endpoint to use. Un endpoint è la combinazione di un contratto di servizio, un'associazione e un indirizzo.An endpoint is the combination of a service contract, a binding, and an address. (Per altre informazioni sugli endpoint, vedere endpoint: Gli indirizzi, associazioni e contratti.) In genere, tali informazioni sono disponibili nel <endpoint > elemento in un file di configurazione dell'applicazione client, ad esempio quella lo strumento Svcutil.exe genera l'errore e viene caricato automaticamente quando si crea il client oggetto.(For more information about endpoints, see Endpoints: Addresses, Bindings, and Contracts.) Typically, this information is located in the <endpoint> element in a client application configuration file, such as the one the Svcutil.exe tool generates, and is loaded automatically when you create your client object. Entrambi i tipi client WCF dispongono inoltre di overload che consentono di specificare a livello di programmazione di queste informazioni.Both WCF client types also have overloads that enable you to programmatically specify this information.

Ad esempio, un file di configurazione generato per un servizio ISampleService usato negli esempi precedenti contiene le informazioni sull'endpoint riportate di seguito.For example, a generated configuration file for an ISampleService used in the preceding examples contains the following endpoint information.

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

Questo file di configurazione specifica un endpoint di destinazione nell'elemento <client>.This configuration file specifies a target endpoint in the <client> element. Per altre informazioni sull'uso di più endpoint di destinazione, vedere la ClientBase<TChannel>.ClientBase<TChannel> o il ChannelFactory<TChannel>.ChannelFactory<TChannel> costruttori.For more information about using multiple target endpoints, see the ClientBase<TChannel>.ClientBase<TChannel> or the ChannelFactory<TChannel>.ChannelFactory<TChannel> constructors.

Chiamate alle operazioniCalling Operations

Dopo avere creato un oggetto client e configurata, creare un blocco try/catch, chiamare le operazioni nello stesso modo che se l'oggetto fosse e chiudere l'oggetto client WCF.Once you have a client object created and configured, create a try/catch block, call operations in the same way that you would if the object were local, and close the WCF client object. Quando l'applicazione client chiama la prima operazione, WCF si apre automaticamente il canale sottostante e il canale sottostante viene chiuso quando l'oggetto viene riciclato.When the client application calls the first operation, WCF automatically opens the underlying channel, and the underlying channel is closed when the object is recycled. In alternativa, è possibile aprire e chiudere il canale in modo esplicito prima o dopo la chiamata ad altre operazioni.(Alternatively, you can also explicitly open and close the channel prior to or subsequent to calling other operations.)

Si supponga, ad esempio, di disporre del contratto di servizio seguente:For example, if you have the following service contract:

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  

È possibile chiamare operazioni creando un oggetto client WCF e chiamando i relativi metodi, come nell'esempio di codice seguente viene illustrato.You can call operations by creating a WCF client object and calling its methods, as the following code example demonstrates. Si noti che l'apertura, chiamare il metodo e la chiusura dell'oggetto client WCF si verifica all'interno di un blocco try/catch singolo.Note that the opening, calling, and closing of the WCF client object occurs within a single try/catch block. Per altre informazioni, vedere accesso ai servizi tramite Client WCF e utilizzare Chiudi e Interrompi per rilasciare le risorse del client WCF.For more information, see Accessing Services Using a WCF Client and Use Close and Abort to release WCF client resources.

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

Gestione degli erroriHandling Errors

In un'applicazione client possono verificarsi eccezioni quando si apre il canale client sottostante (sia in modo esplicito che automaticamente chiamando un'operazione), quando si usa l'oggetto client o l'oggetto canale per chiamare operazioni o quando si chiude il canale client sottostante.Exceptions can occur in a client application when opening the underlying client channel (whether explicitly or automatically by calling an operation), using the client or channel object to call operations, or when closing the underlying client channel. Oltre a gestire qualsiasi oggetto System.TimeoutException generato come risultato di errori SOAP restituiti dalle operazioni, le applicazioni dovrebbero essere configurate per gestire almeno possibili eccezioni System.ServiceModel.CommunicationException e System.ServiceModel.FaultException.It is recommended at a minimum that applications expect to handle possible System.TimeoutException and System.ServiceModel.CommunicationException exceptions in addition to any System.ServiceModel.FaultException objects thrown as a result of SOAP faults returned by operations. Gli errori SOAP specificati nel contratto dell'operazione vengono generati nelle applicazioni client come oggetto System.ServiceModel.FaultException<TDetail> dove il parametro di tipo è il tipo di dettaglio dell'errore SOAP.SOAP faults specified in the operation contract are raised to client applications as a System.ServiceModel.FaultException<TDetail> where the type parameter is the detail type of the SOAP fault. Per altre informazioni sulla gestione di condizioni di errore in un'applicazione client, vedere Sending and Receiving Faults.For more information about handling error conditions in a client application, see Sending and Receiving Faults. Per un esempio completo che mostra come gestire gli errori in un client, vedere previsto eccezioni.For a complete sample the shows how to handle errors in a client, see Expected Exceptions.

Configurazione e protezione dei clientConfiguring and Securing Clients

La configurazione di un client inizia con il caricamento obbligatorio di informazioni sull'endpoint di destinazione per il client o per l'oggetto del canale, generalmente da un file di configurazione, sebbene sia possibile caricare queste informazioni anche a livello di programmazione usando i costruttori e le proprietà del client.Configuring a client starts with the required loading of target endpoint information for the client or channel object, usually from a configuration file, although you can also load this information programmatically using the client constructors and properties. Per attivare determinati comportamenti del client e per numerosi scenari di sicurezza sono tuttavia necessarie operazioni di configurazione aggiuntive.However, additional configuration steps are required to enable certain client behavior and for many security scenarios.

I requisiti di sicurezza per i contratti di servizio, ad esempio, vengono dichiarati nell'interfaccia del contratto di servizio e se lo strumento Svcutil.exe ha creato un file di configurazione, questo file contiene in genere un'associazione in grado di supportare i requisiti di sicurezza del servizio.For example, security requirements for service contracts are declared in the service contract interface, and if Svcutil.exe created a configuration file, that file usually contains a binding that is capable of supporting the security requirements of the service. In alcuni casi può essere però necessaria un'ulteriore configurazione della protezione, ad esempio la configurazione di credenziali client.In some cases, however, more security configuration may be required, such as configuring client credentials. Per informazioni complete sulla configurazione di sicurezza per i client WCF, vedere protezione di client.For complete information about the configuration of security for WCF clients, see Securing Clients.

Nelle applicazioni client possono essere inoltre abilitate alcune modifiche personalizzate, ad esempio comportamenti personalizzati nella fase di esecuzione.In addition, some custom modifications can be enabled in client applications, such as custom run-time behaviors. Per altre informazioni su come configurare un comportamento client personalizzato, vedere configurazione dei comportamenti Client.For more information about how to configure a custom client behavior, see Configuring Client Behaviors.

Creazione di oggetti di callback per i servizi duplexCreating Callback Objects for Duplex Services

I servizi duplex specificano un contratto di callback che l'applicazione client deve implementare per fornire un oggetto di callback affinché il servizio esegua la chiamata in base ai requisiti del contratto.Duplex services specify a callback contract that the client application must implement in order to provide a callback object for the service to call according to the requirements of the contract. Sebbene gli oggetti di callback non siano servizi completi (ad esempio, non è possibile avviare un canale con un oggetto di callback), ai fini dell'implementazione e della configurazione possono essere considerati come una specie di servizio.Although callback objects are not full services (for example, you cannot initiate a channel with a callback object), for the purposes of implementation and configuration they can be thought of as a kind of service.

I client di servizi duplex devono:Clients of duplex services must:

  • Implementare una classe di contratto di callback.Implement a callback contract class.

  • Creare un'istanza della classe di implementazione del contratto di callback e usarla per creare il System.ServiceModel.InstanceContext oggetto passato al costruttore del client WCF.Create an instance of the callback contract implementation class and use it to create the System.ServiceModel.InstanceContext object that you pass to the WCF client constructor.

  • Richiamare operazioni e gestire callback di operazioni.Invoke operations and handle operation callbacks.

Duplex WCF client gli oggetti funzione, ad esempio le rispettive controparti non duplex, con l'eccezione che espongono le funzionalità necessarie per supportare i callback, inclusa la configurazione del servizio di callback.Duplex WCF client objects function like their nonduplex counterparts, with the exception that they expose the functionality necessary to support callbacks, including the configuration of the callback service.

È possibile controllare, ad esempio, i vari aspetti del comportamento degli oggetti di callback in fase di esecuzione usando proprietà dell'attributo System.ServiceModel.CallbackBehaviorAttribute nella classe di callback.For example, you can control various aspects of callback object runtime behavior by using properties of the System.ServiceModel.CallbackBehaviorAttribute attribute on the callback class. Un altro esempio è l'uso della classe System.ServiceModel.Description.CallbackDebugBehavior per attivare la restituzione di informazioni sull'eccezione ai servizi che chiamano l'oggetto di callback.Another example is the use of the System.ServiceModel.Description.CallbackDebugBehavior class to enable the return of exception information to services that call the callback object. Per altre informazioni, vedere servizi Duplex.For more information, see Duplex Services. Per un esempio completo, vedere Duplex.For a complete sample, see Duplex.

Nei computer Windows XP che eseguono Internet Information Services (IIS) 5.1, i client duplex devono specificare un indirizzo client di base usando la classe System.ServiceModel.WSDualHttpBinding. In caso contrario verrà generata un'eccezione.On Windows XP computers running Internet Information Services (IIS) 5.1, duplex clients must specify a client base address using the System.ServiceModel.WSDualHttpBinding class or an exception is thrown. Nel codice di esempio seguente viene illustrato come eseguire questa procedura nel codice.The following code example shows how to do this 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/")

Il codice seguente mostra come eseguire la procedura in un file di configurazione.The following code shows how to do this in a configuration file

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

Chiamate ai servizi in modo asincronoCalling Services Asynchronously

La modalità in cui vengono chiamate le operazioni dipende interamente dallo sviluppatore client.How operations are called is entirely up to the client developer. Ciò è dovuto al fatto che i messaggi che costituiscono un'operazione possono essere mappati a metodi sincroni o asincroni quando vengono espressi in codice gestito.This is because the messages that make up an operation can be mapped to either synchronous or asynchronous methods when expressed in managed code. Pertanto, se si desidera compilare un client che chiama operazioni in modo asincrono, è possibile usare Svcutil.exe per generare codice client asincrono usando l'opzione /async.Therefore, if you want to build a client that calls operations asynchronously, you can use Svcutil.exe to generate asynchronous client code using the /async option. Per altre informazioni, vedere Procedura: Chiamare operazioni del servizio in modo asincrono.For more information, see How to: Call Service Operations Asynchronously.

Chiamate ai servizi mediante canali client di WCFCalling Services Using WCF Client Channels

I tipi di client WCF estendono ClientBase<TChannel>, che a sua volta deriva da System.ServiceModel.IClientChannel interfaccia da esporre il sistema di canali sottostante.WCF client types extend ClientBase<TChannel>, which itself derives from System.ServiceModel.IClientChannel interface to expose the underlying channel system. È possibile richiamare servizi usando il contratto di servizio di destinazione con la classe System.ServiceModel.ChannelFactory<TChannel>.You can invoke services by using the target service contract with the System.ServiceModel.ChannelFactory<TChannel> class. Per informazioni dettagliate, vedere architettura Client WCF.For details, see WCF Client Architecture.

Vedere ancheSee also