Estensione dei client
In un'applicazione chiamante, il livello del modello di servizio è responsabile della conversione delle chiamate ai metodi contenute nel codice dell'applicazione in messaggi in uscita, del loro inserimento nei canali sottostanti, della conversione dei risultati in valori restituiti e parametri out nel codice dell'applicazione e della restituzione dei risultati al chiamante. Le estensioni del modello di servizi modificano o implementano il comportamento e le funzionalità dell'esecuzione o della comunicazione relativamente a funzionalità del client o del dispatcher, comportamenti personalizzati, intercettazione di messaggi e parametri e altre funzionalità di estendibilità.
In questo argomento viene illustrato come utilizzare le classi ClientRuntime e ClientOperation in un'applicazione client Windows Communication Foundation (WCF) per modificare il comportamento di esecuzione predefinito di un client WCF o per intercettare o modificare messaggi, parametri o valori restituiti prima o dopo il loro invio o recupero dal livello del canale. Per ulteriori informazioni sull'estensione della fase di esecuzione del servizio, vedere Estensione dei dispatcher. Per altre informazioni sui comportamenti che modificano e inseriscono oggetti di personalizzazione nel runtime client, vedere Configurazione ed estensione del runtime con comportamenti.
Client
In un client, un oggetto o un canale client WCF converte le chiamate ai metodi in messaggi in uscita e i messaggi in ingresso in risultati di operazioni che vengono restituiti all'applicazione chiamante. Per altre informazioni sui tipi di client, vedere Architettura client WCF.
I tipi di client WCF dispongono di tipi in fase di esecuzione che gestiscono questa funzionalità a livello di endpoint e di operazione. Quando in un'applicazione viene eseguita una chiamata a un'operazione, la classe ClientOperation converte gli oggetti in uscita in un messaggio, elabora gli intercettori, conferma che la chiamata in uscita è conforme al contratto di destinazione e passa il messaggio in uscita alla classe ClientRuntime, che è responsabile della creazione e della gestione dei canali in uscita (e dei canali in ingresso in caso di servizi duplex), della gestione dell'elaborazione supplementare dei messaggi in uscita (ad esempio la modifica dell'intestazione), dell'elaborazione degli intercettori del messaggio in entrambe le direzioni e dell'instradamento delle chiamate duplex in ingresso all'oggetto DispatchRuntime sul lato client appropriato. Le classi ClientOperation e ClientRuntime forniscono servizi simili quando i messaggi (compresi gli errori) vengono restituiti al client.
Queste due classi di runtime costituiscono l'estensione principale per personalizzare l'elaborazione degli oggetti e dei canali client WCF. La classe ClientRuntime consente agli utenti di intercettare ed estendere l'esecuzione del client in tutti i messaggi del contratto. La classe ClientOperation consente agli utenti di intercettare ed estendere l'esecuzione del client per tutti i messaggi di una determinata operazione.
Per la modifica delle proprietà o l'inserimento di personalizzazioni, si utilizzano i comportamenti del contratto, dell'endpoint e dell'operazione. Per altre informazioni su come usare questi tipi di comportamenti per eseguire personalizzazioni del runtime client, vedere Configurazione ed estensione del runtime con comportamenti.
Scenari
Esistono vari motivi per estendere il sistema client, tra cui:
Convalida di messaggi personalizzata. È possibile che un utente desideri imporre che un messaggio sia valido per un certo schema. A tale scopo, implementare l'interfaccia IClientMessageInspector e assegnare l'implementazione alla proprietà MessageInspectors. Per esempi, vedere Procedura: Esaminare o modificare messaggi nel client e Procedura: Esaminare o modificare messaggi nel client.
Registrazione di messaggi personalizzata. È possibile che un utente desideri controllare e registrare un set di messaggi dell'applicazione che passano attraverso un endpoint. Questa operazione può essere eseguita anche con le interfacce degli intercettori di messaggi.
Trasformazioni di messaggi personalizzate. Anziché modificare il codice dell'applicazione, è possibile che l'utente desideri applicare determinate trasformazioni al messaggio nel runtime (ad esempio per il controllo delle versioni). Anche in questo caso, l'operazione può essere eseguita con le interfacce degli intercettori di messaggi.
Modello di dati personalizzato. È possibile che un utente desideri un modello di dati o di serializzazione diverso da quelli supportati per impostazione predefinita in WCF (ovvero oggetti System.Runtime.Serialization.DataContractSerializer, System.Xml.Serialization.XmlSerializer e System.ServiceModel.Channels.Message). A questo scopo, è possibile implementare le interfacce dei formattatori di messaggi. Per ulteriori informazioni, vedere l'interfaccia System.ServiceModel.Dispatcher.IClientMessageFormatter e la proprietà ClientOperation.Formatter.
Convalida di parametri personalizzata. È possibile che un utente desideri imporre che i parametri tipizzati siano validi (a differenza di XML). A questo scopo, è possibile usare le interfacce di controllo dei parametri. Per un esempio, vedere Procedura: Esaminare o modificare parametri o Convalida client.
Utilizzo della classe ClientRuntime
La classe ClientRuntime è un punto di estensibilità a cui è possibile aggiungere oggetti di estensione che intercettano i messaggi ed estendono il comportamento del client. Gli oggetti di intercettamento possono elaborare tutti i messaggi di un contratto specifico, elaborare solo i messaggi di operazioni particolari, eseguire l'inizializzazione di un canale personalizzata e implementare altri comportamenti dell'applicazione client personalizzati.
La proprietà CallbackDispatchRuntime restituisce l'oggetto runtime di invio per i client di callback avviati dal servizio.
La proprietà OperationSelector accetta un oggetto selettore dell'operazione personalizzato.
La proprietà ChannelInitializers consente di aggiungere un inizializzatore del canale che può controllare o modificare il canale client.
La proprietà Operations ottiene una raccolta di oggetti ClientOperation alla quale è possibile aggiungere intercettatori di messaggi personalizzati che forniscono la funzionalità specifica ai messaggi di quell'operazione.
La proprietà ManualAddressing consente a un'applicazione di disattivare alcune intestazioni di indirizzamento automatico per controllare direttamente l'indirizzamento.
La proprietà Via imposta il valore della destinazione del messaggio a livello di trasporto per supportare gli intermediari e altri scenari.
La proprietà MessageInspectors ottiene una raccolta di oggetti IClientMessageInspector alla quale è possibile aggiungere intercettatori di messaggi personalizzati per tutti i messaggi che passano per un client WCF.
Esistono inoltre altre proprietà che recuperano le informazioni del contratto:
Se il client WCF è un client WCF duplex, nelle proprietà seguenti vengono inoltre recuperate le informazioni del client WCF sul callback:
Per estendere l'esecuzione del client WCF attraverso un intero client WCF, esaminare le proprietà disponibili sulla classe ClientRuntime per verificare se la modifica di una proprietà o l'implementazione di un'interfaccia e la relativa aggiunta a una proprietà crea la funzionalità desiderata. Una volta scelta una particolare estensione da compilare, inserirla nella proprietà ClientRuntime appropriata implementando un comportamento del client che fornisca accesso alla classe ClientRuntime quando viene richiamato.
Per inserire oggetti di estensione personalizzati in una raccolta, è possibile utilizzare un comportamento dell'operazione (un oggetto che implementa IOperationBehavior), un comportamento del contratto (un oggetto che implementa IContractBehavior) o un comportamento dell'endpoint (un oggetto che implementa IEndpointBehavior). L'oggetto del comportamento da installare viene aggiunto alla raccolta appropriata di comportamenti a livello di codice, in modo dichiarativo (implementando un attributo personalizzato) o implementando un oggetto BehaviorExtensionElement personalizzato per consentire al comportamento di essere inserito utilizzando un file di configurazione dell'applicazione. Per informazioni dettagliate, vedere Configurazione ed estensione del runtime con i comportamenti.
Per esempi che illustrano l'intercettazione in un client WCF, vedere Procedura: Esaminare o modificare i messaggi sul client.
Utilizzo della classe ClientOperation
Nella classe ClientOperation è possibile eseguire modifiche della fase di esecuzione del client e questa classe rappresenta il punto di inserimento per le estensioni personalizzate nell'ambito di una sola operazione del servizio. (Per modificare il comportamento della fase di esecuzione del client per tutti i messaggi di un contratto, utilizzare la classe ClientRuntime).
Usare la proprietà Operations per individuare l'oggetto ClientOperation che rappresenta un'operazione specifica del servizio. Le proprietà seguenti consentono di inserire oggetti personalizzati nel sistema client WCF:
Utilizzare la proprietà Formatter per inserire un'implementazione personalizzata dell'interfaccia IClientMessageFormatter di un'operazione o per modificare il formattatore corrente.
Utilizzare la proprietà ParameterInspectors per inserire un'implementazione personalizzata dell'interfaccia IParameterInspector o per modificare l'interfaccia corrente.
Le proprietà seguenti consentono di modificare il sistema in interazione con il formattatore e i controlli del parametro personalizzati:
Utilizzare la proprietà SerializeRequest per controllare la serializzazione di un messaggio in uscita.
Utilizzare la proprietà DeserializeReply per controllare la deserializzazione di un messaggio in entrata.
Utilizzare la proprietà Action per controllare l'azione WS-Addressing del messaggio di richiesta.
Utilizzare le proprietà BeginMethod e EndMethod per specificare quali metodi del client WCF vengono associati a un'operazione asincrona.
Utilizzare la proprietà FaultContractInfos per ottenere una raccolta contenente i tipi che possono comparire negli errori SOAP come tipi di dettaglio.
Utilizzare le proprietà IsInitiating e IsTerminating per controllare se una sessione viene rispettivamente avviata o eliminata quando viene chiamata l'operazione.
Utilizzare la proprietà IsOneWay per controllare se l'operazione è un'operazione unidirezionale.
Utilizzare la proprietà Parent per ottenere l'oggetto contenitore ClientRuntime.
Utilizzare la proprietà Name per ottenere il nome dell'operazione.
Utilizzare la proprietà SyncMethod per controllare quale metodo viene mappato all'operazione.
Per estendere l'esecuzione del client WCF in una sola operazione del servizio, esaminare le proprietà disponibili sulla classe ClientOperation per verificare se la modifica di una proprietà o l'implementazione di un'interfaccia e la relativa aggiunta a una proprietà crea la funzionalità desiderata. Una volta scelta una particolare estensione da compilare, inserirla nella proprietà ClientOperation appropriata implementando un comportamento del client che fornisca accesso alla classe ClientOperation quando viene richiamato. All'interno di tale comportamento è quindi possibile modificare la proprietà ClientRuntime in base alle esigenze.
In genere, è sufficiente l'implementazione di un comportamento dell'operazione (un oggetto che implementa l'interfaccia IOperationBehavior), ma è anche possibile utilizzare comportamenti dell'endpoint e del contratto per ottenere lo stesso risultato individuando la classe OperationDescription per una particolare operazione e allegandovi il comportamento. Per informazioni dettagliate, vedere Configurazione ed estensione del runtime con i comportamenti.
Per utilizzare il comportamento personalizzato dalla configurazione, installare il comportamento utilizzando un gestore della sezione di configurazione dei comportamenti personalizzati. È inoltre possibile installare il comportamento creando un attributo personalizzato.
Per esempi che illustrano l'intercettazione in un client WCF, vedere Procedura: Esaminare o modificare i parametri.