Condividi tramite

Panoramica del client WCF

In questa sezione vengono descritte le attività delle applicazioni client, come configurare, creare e usare un client Windows Communication Foundation (WCF) e come proteggere le applicazioni client.

Uso di oggetti client WCF

Un'applicazione client è un'applicazione gestita che usa un client WCF per comunicare con un'altra applicazione. La creazione di un'applicazione client per un servizio WCF richiede la procedura seguente:

  1. Ottenere il contratto di servizio, le associazioni di connessione e le informazioni sull'indirizzo per un punto finale del servizio.

  2. Creare un client WCF usando tali informazioni.

  3. Chiamare le operazioni.

  4. Chiudere l'oggetto client WCF.

Le sezioni seguenti illustrano questi passaggi e forniscono brevi introduzione ai problemi seguenti:

  • Gestione degli errori,

  • Configurazione e protezione dei client.

  • Creazione di oggetti di callback per i servizi duplex.

  • Chiamare i servizi in modo asincrono.

  • Chiamare i servizi tramite canali client.

Ottenere il contratto di servizio, i binding e gli indirizzi

In WCF, i servizi e i client modellano contratti usando attributi, interfacce e metodi gestiti. Per connettersi a un servizio in un'applicazione client, è necessario ottenere le informazioni sul tipo di contratto di servizio. In genere, si ottengono informazioni sul tipo per il contratto di servizio usando lo strumento Utilità Metadati di ServiceModel (Svcutil.exe). L'utilità scarica i metadati dal servizio, lo converte in un file di codice sorgente gestito nel linguaggio preferito e crea un file di configurazione dell'applicazione client che è possibile usare per configurare l'oggetto client WCF. Ad esempio, se si intende creare un oggetto client WCF per richiamare un MyCalculatorServiceoggetto e si sa che i metadati per tale servizio vengono pubblicati in http://computerName/MyCalculatorService/Service.svc?wsdl, nell'esempio di codice seguente viene illustrato come usare Svcutil.exe per ottenere un ClientCode.vb file contenente il contratto di servizio nel codice gestito.

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

È possibile compilare il codice del contratto nell'applicazione client o in un altro assembly che l'applicazione client può quindi usare per creare un oggetto client WCF. È possibile usare il file di configurazione per configurare l'oggetto client per connettersi correttamente al servizio .

Per un esempio di questo processo, vedere Procedura: Creare un client. Per altre informazioni complete sui contratti, vedere Contratti.

Creare un oggetto client WCF

Un client WCF è un oggetto locale che rappresenta un servizio WCF in un formato che il client può usare per comunicare con il servizio remoto. I tipi di client WCF implementano il contratto di servizio di destinazione, quindi quando ne viene creato uno e configurato, è quindi possibile usare direttamente l'oggetto client per richiamare le operazioni del servizio. Il runtime WCF converte le chiamate al metodo in messaggi, li invia al servizio, rimane in ascolto della risposta e restituisce tali valori all'oggetto client WCF come valori restituiti o outref parametri.

È anche possibile usare oggetti canale client WCF per connettersi ai servizi e usarli. Per ulteriori dettagli, vedere Architettura client WCF.

Creazione di un nuovo oggetto WCF

Per illustrare l'uso di una ClientBase<TChannel> classe, si supponga che il contratto di servizio semplice seguente sia stato generato da un'applicazione di servizio.

Annotazioni

Se si usa Visual Studio per creare il client WCF, gli oggetti vengono caricati automaticamente nel visualizzatore oggetti quando si aggiunge un riferimento al servizio al progetto.

[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 utilizza Visual Studio, esaminare il codice del contratto generato per trovare il tipo che estende ClientBase<TChannel> e l'interfaccia ISampleService del contratto di servizio. In questo caso, il tipo è simile al codice seguente:

[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 oggetto locale usando uno dei costruttori, configurati e quindi usati per connettersi a un servizio del tipo ISampleService.

È consigliabile creare prima l'oggetto client WCF e quindi usarlo e chiuderlo all'interno di un singolo blocco try/catch. Non usare l'istruzione using (Using in Visual Basic) perché può mascherare le eccezioni in determinate modalità di errore. Per ulteriori informazioni, vedere le sezioni seguenti e Usare Chiudi e Interrompi per rilasciare le risorse client WCF.

Contratti, vincoli e indirizzi

Prima di poter creare un oggetto client WCF, è necessario configurare l'oggetto client. In particolare, deve avere un endpoint di servizio da usare. Un endpoint è la combinazione di un contratto di servizio, un binding e un indirizzo. Per altre informazioni sugli endpoint, vedere Endpoint: indirizzi, associazioni e contratti. In genere, queste informazioni si trovano nell'elemento <endpoint> in un file di configurazione dell'applicazione client, ad esempio quello generato dallo strumento Svcutil.exe e viene caricato automaticamente quando si crea l'oggetto client. Entrambi i tipi di client WCF dispongono anche di overload che consentono di specificare queste informazioni a livello di codice.

Ad esempio, un file di configurazione generato per un ISampleService oggetto usato negli esempi precedenti contiene le informazioni sull'endpoint seguenti.

<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> . Per ulteriori informazioni sull'uso di più endpoint di destinazione, consultare i costruttori ClientBase<TChannel> o ChannelFactory<TChannel>.

Operazioni di chiamata

Dopo aver creato e configurato un oggetto client, creare un blocco try/catch, chiamare le operazioni nello stesso modo in cui si farebbe se l'oggetto fosse locale e chiudere l'oggetto client WCF. Quando l'applicazione client chiama la prima operazione, WCF apre automaticamente il canale sottostante e il canale sottostante viene chiuso quando l'oggetto viene riciclato. In alternativa, è anche possibile aprire e chiudere in modo esplicito il canale prima o successivamente a chiamare altre operazioni.

Ad esempio, se si dispone del contratto di servizio seguente:

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 le operazioni creando un oggetto client WCF e chiamando i relativi metodi, come illustrato nell'esempio di codice seguente. L'apertura, la chiamata e la chiusura dell'oggetto client WCF si verifica all'interno di un singolo blocco try/catch. Per altre informazioni, vedere Accesso ai servizi tramite un client WCF e Utilizzo di chiusura e interruzione per rilasciare le risorse client WCF.

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 errori

Le eccezioni possono verificarsi in un'applicazione client quando si apre il canale client sottostante (in modo esplicito o automatico chiamando un'operazione), usando il client o l'oggetto canale per chiamare le operazioni o quando si chiude il canale client sottostante. È consigliabile almeno che le applicazioni si aspettano di gestire possibili System.TimeoutException eccezioni e System.ServiceModel.CommunicationException oltre a qualsiasi System.ServiceModel.FaultException oggetto generato in seguito a errori SOAP restituiti dalle operazioni. Gli fault SOAP specificati nel contratto dell'operazione vengono sollevati alle applicazioni client come un System.ServiceModel.FaultException<TDetail>, dove il parametro di tipo è il tipo di dettaglio del fault SOAP. Per altre informazioni sulla gestione delle condizioni di errore in un'applicazione client, vedere Invio e ricezione di errori. Per un esempio completo, mostra come gestire gli errori in un client, vedere Eccezioni previste.

Configurazione e protezione dei client

La configurazione di un client inizia con il caricamento richiesto delle informazioni sull'endpoint di destinazione per l'oggetto client o canale, in genere da un file di configurazione, anche se è anche possibile caricare queste informazioni a livello di codice usando i costruttori e le proprietà client. Tuttavia, sono necessari passaggi di configurazione aggiuntivi per abilitare determinati comportamenti del client e per molti scenari di sicurezza.

Ad esempio, i requisiti di sicurezza per i contratti di servizio vengono dichiarati nell'interfaccia del contratto di servizio e, se Svcutil.exe creato un file di configurazione, tale file contiene in genere un'associazione in grado di supportare i requisiti di sicurezza del servizio. In alcuni casi, tuttavia, potrebbe essere necessaria una configurazione di sicurezza maggiore, ad esempio la configurazione delle credenziali client. Per informazioni complete sulla configurazione della sicurezza per i client WCF, vedere Protezione dei client.

Inoltre, alcune modifiche personalizzate possono essere abilitate nelle applicazioni client, ad esempio comportamenti di runtime personalizzati. Per altre informazioni su come configurare un comportamento client personalizzato, vedere Configurazione dei comportamenti del client.

Creazione di oggetti callback per i servizi duplex

I servizi duplex specificano un contratto di callback che l'applicazione client deve implementare per fornire un oggetto callback per consentire al servizio di chiamare in base ai requisiti del contratto. Anche se gli oggetti callback non sono servizi completi (ad esempio, non è possibile avviare un canale con un oggetto callback), ai fini dell'implementazione e della configurazione che possono essere considerati come un tipo di servizio.

I clienti dei servizi duplex devono:

  • Implementare una classe del contratto di callback.

  • Creare un'istanza della classe di implementazione del contratto di callback e utilizzarla per creare l'oggetto System.ServiceModel.InstanceContext passato al costruttore client WCF.

  • Richiamare le operazioni e gestire i callback delle operazioni.

Gli oggetti client WCF duplex funzionano come le controparti nonduplex, con l'eccezione che espongono le funzionalità necessarie per supportare i callback, inclusa la configurazione del servizio di callback.

Ad esempio, è possibile controllare vari aspetti del comportamento di runtime dell'oggetto callback usando le proprietà dell'attributo System.ServiceModel.CallbackBehaviorAttribute nella classe di callback. Un altro esempio è l'uso della System.ServiceModel.Description.CallbackDebugBehavior classe per abilitare la restituzione di informazioni sulle eccezioni ai servizi che chiamano l'oggetto callback. Per altre informazioni, vedere Servizi duplex. Per un esempio completo, vedere Duplex.

Nei computer Windows XP che eseguono Internet Information Services (IIS) 5.1, i client duplex devono specificare un indirizzo di base client utilizzando la System.ServiceModel.WSDualHttpBinding classe o viene generata un'eccezione. Nell'esempio di codice seguente viene illustrato come eseguire questa operazione nel codice.

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 illustra come eseguire questa operazione in un file di configurazione

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

Chiamare i Servizi Asincronicamente

La modalità di chiamata delle operazioni dipende interamente dallo sviluppatore client. Ciò è dovuto al fatto che i messaggi che costituiscono un'operazione possono essere mappati a metodi sincroni o asincroni se espressi in codice gestito. Pertanto, se si vuole creare un client che chiama le operazioni in modo asincrono, è possibile usare Svcutil.exe per generare codice client asincrono usando l'opzione /async . Per ulteriori informazioni, vedere Come chiamare le operazioni del servizio in modo asincrono.

Chiamata di servizi tramite canali client WCF

I tipi di client WCF estendono ClientBase<TChannel>, che a sua volta deriva da un'interfaccia System.ServiceModel.IClientChannel per esporre il sistema di canali sottostante. È possibile richiamare i servizi usando il contratto di servizio di destinazione con la System.ServiceModel.ChannelFactory<TChannel> classe . Per ulteriori dettagli, vedere Architettura client WCF.

Vedere anche

  • Last updated on