Creazione di un proxy di servizio Web XML

  • Articolo

Per definizione i servizi Web XML possono essere utilizzati per comunicare in rete con protocolli standard, incluso il protocollo SOAP. Un client e un servizio Web XML possono quindi comunicare utilizzando messaggi SOAP i quali incapsulano i parametri in e out come XML. Per i client di servizi Web XML la classe proxy gestisce il mapping dei parametri agli elementi XML e il conseguente invio del messaggio SOAP in rete.

Se è presente una descrizione del servizio, è possibile generare una classe proxy a condizione che tale descrizione sia conforme al linguaggio WSDL (Web Services Description Language). La descrizione del servizio definisce la modalità di comunicazione con un servizio Web XML. Con una descrizione, è possibile creare una classe proxy con lo strumento Wsdl.exe. Un client del servizio Web XML può quindi richiamare i metodi della classe proxy, che comunicano con un servizio Web XML tramite la rete elaborando i messaggi SOAP inviati e ricevuti dal servizio stesso. Poiché la classe proxy comunica con il servizio Web XML tramite Internet, è consigliabile verificare che la proprietà Url della classe proxy faccia riferimento a una destinazione attendibile.

Per impostazione predefinita, la classe proxy utilizza il protocollo SOAP su HTTP per comunicare con il servizio Web XML. Tuttavia, con lo strumento Wsdl.exe è possibile generare classi proxy per comunicare con un servizio Web XML, utilizzando il protocollo HTTP-GET o HTTP-POST. Per specificare se la classe proxy deve utilizzare il protocollo HTTP-GET o HTTP-POST, includere l'opzione /protocol nello strumento Wsdl.exe, come indicato nella tabella seguente.

Per generare una classe proxy di servizi Web XML

  • Al prompt dei comandi, utilizzare lo strumento Wsdl.exe per creare una classe proxy indicando (come minimo) l'URL di un servizio Web XML o una descrizione del servizio oppure il percorso di una descrizione salvata.

    Wsdl /language:language  /protocol:protocol /namespace:myNameSpace /out:filename /username:username /password:password /domain:domain <url or path>

    Nota: gli argomenti elencati in precedenza rappresentano gli argomenti comunemente utilizzati per lo strumento Wsdl.exe. Per ulteriori informazioni sulla sintassi completa dello strumento Wsdl.exe, vedere ** Strumento del linguaggio di descrizione dei servizi Web (Wsdl.exe).

    Parametro Valore
    <url or path> URL o percorso di una descrizione del servizio, ovvero del file in cui viene descritto il servizio Web XML con il linguaggio WSDL.

    Se si specifica un file, indicare un file contenente la descrizione del servizio. Ad esempio:

    mywebservice.wsdl

    Se si specifica l'URL, indicare un URL che faccia riferimento a una pagina ASMX o restituisca la descrizione del servizio. Per i servizi Web XML creati con ASP.NET, è possibile restituire una descrizione del servizio aggiungendo ?WSDL all'URL del servizio Web XML. Ad esempio,

    https://www.contoso.com/MyWebService.asmx?WSDL
    /language:language Linguaggio con cui è stata creata la classe proxy. Le opzioni disponibili sono CS, VB e JS, che indicano, rispettivamente, C#, Visual Basic .NET e JScript .NET. Il linguaggio predefinito è C#. (Facoltativo)
    /protocol:protocol Protocollo utilizzato per comunicare con i metodi dei servizi Web XML. Le opzioni disponibili sono SOAP, HTTP-GET e HTTP-POST. Il protocollo predefinito è SOAP. (Facoltativo)
    /namespace:myNameSpace Spazio dei nomi del proxy generato. Il valore predefinito è lo spazio dei nomi globale. (Facoltativo)
    /out:filename Nome del file da creare contenente la classe proxy. Il nome predefinito è basato sul nome della classe che implementa il servizio Web XML. (Facoltativo)
    /username:username Nome utente da utilizzare per il collegamento a un server Web che richiede l'autenticazione. (Facoltativo)
    /password:password Password da utilizzare per il collegamento a un server Web che richiede l'autenticazione. (Facoltativo)
    /domain:domain Dominio da utilizzare per il collegamento a un server Web che richiede l'autenticazione. (Facoltativo)

Informazioni dettagliate sulla classe proxy generata

Quando lo strumento Wsdl.exe viene utilizzato per generare una classe proxy, viene generato un singolo file di origine nel linguaggio specificato. Il file include la classe proxy che espone sia i metodi sincroni sia i metodi asincroni per ogni metodo del servizio Web XML. Se, ad esempio, un servizio Web XML contiene un metodo denominato Add, la classe proxy presenta i metodi seguenti per chiamare il metodo Add del servizio Web XML: Add, BeginAdd e EndAdd. Il metodo Add della classe proxy viene utilizzato per comunicare con il metodo Add del servizio Web XML in maniera sincrona, mentre i metodi BeginAdd e EndAdd vengono utilizzati per comunicare in modo asincrono. Per ulteriori informazioni sulle comunicazione con metodi di servizi Web XML in modo asincrono, vedere Comunicazione asincrona con servizi Web XML.

Ogni metodo della classe proxy generata include il codice appropriato per comunicare con il metodo del servizio Web XML. Se si verifica un errore durante la comunicazione tra il servizio Web XML e la classe proxy, viene generata un'eccezione. Per ulteriori informazioni sulla gestione delle eccezioni, vedere Gestione e generazione di eccezioni nei servizi Web XML.

L'ordine dei parametri può risultare diverso nell'ordine definito nel metodo del servizio Web XML rispetto al metodo associato della classe proxy. Nella maggior parte dei casi l'ordine sarà identico. Tuttavia, se il servizio Web XML prevede messaggi SOAP con formattazione Document, vi è un caso in cui l'ordine dei parametri non corrisponderà. Se in un metodo di servizio Web XML sono definiti i parametri out prima di un parametro in, i parametri out vengono collocati dopo tutti i parametri in nella classe proxy. Nell'esempio di codice seguente il parametro out outStr è stato dichiarato prima del parametro in inStr nel metodo MyWebMethod del servizio Web XML, mentre nella classe proxy, il parametro inStr è dichiarato prima del parametro outStr.

In alcuni casi, la classe proxy generata da WSDL.exe adotta il principio del minimo comun denominatore per eseguire il casting degli oggetti su un tipo specificato nella descrizione di un servizio. È pertanto possibile che il tipo così generato, utilizzato nella classe proxy, non sia quello previsto dallo sviluppatore. Quando, ad esempio, nella descrizione di un servizio viene utilizzato un tipo ArrayList, nella classe proxy generata da WSDL.exe verrà impiegata una matrice di Object. Per assicurare la correttezza dei cast dei tipi di oggetto, aprire il file contenente la classe proxy generata e correggere i tipi di oggetto non corrispondenti a quanto desiderato.

' Declare MyWebMethod in the XML Web service.
MyWebMethod(ByRef outStr As String, inStr As String)

' This is the corresponding MyWebMethod in the proxy class.
MyWebMethod(inStr As String, ByRef outStr As String)
[C#]
// Declare MyWebMethod in the XML Web service.
MyWebMethod(out string outStr, string inStr)

// This is the corresponding MyWebMethod in the proxy class.
MyWebMethod(string inStr, out string outStr).

In alcuni casi, la classe proxy generata da WSDL.exe adotta il principio del minimo comun denominatore per eseguire il casting degli oggetti su un tipo specificato nella descrizione di un servizio. È pertanto possibile che il tipo così generato, utilizzato nella classe proxy, non sia quello previsto dallo sviluppatore. Quando, ad esempio, nella descrizione di un servizio viene utilizzato un tipo ArrayList, nella classe proxy generata da WSDL.exe verrà impiegata una matrice di Object. Per assicurare la correttezza dei cast dei tipi di oggetto, aprire il file contenente la classe proxy generata e correggere i tipi di oggetto non corrispondenti a quanto desiderato.

Avvisi generati dallo strumento Wsdl.exe

Quando vengono fornite più descrizioni di servizi in Wsdl.exe, possono essere generati i due messaggi di errore seguenti:

  • Avviso: verrà ignorata la descrizione del servizio duplicato con TargetNamespace =<spazio dei nomi dello schema> da <URI schema>.

    Il messaggio indica che l'impostazione TargetNamespace per due o più descrizioni di servizi fornite è identica. Poiché TargetNamespace deve essere un identificatore univoco di un determinato documento XML, nel caso specifico una descrizione di servizio, lo strumento Wsdl.exe presume che le due descrizioni di servizio siano identiche e pertanto crea solo una classe proxy per una delle descrizioni di servizi. Se questo non fosse il risultato desiderato, è possibile modificare questa condizione. Per le descrizioni di servizi Web XML creati con ASP.NET, è possibile applicare un attributo WebService che specifica una proprietà Namespace univoca per la classe che implementa il servizio Web XML. Tale proprietà Namespace viene utilizzata come impostazione TargetNamespace nella descrizione per identificare in maniera univoca il servizio Web XML. Per ulteriori informazioni sull'impostazione della proprietà Namespace, vedere Applicazione dell'attributo WebService.

  • Avviso: verrà ignorato lo schema duplicato con TargetNamespace=<Spazio dei nomi schema> da <URI schema>.

    Il messaggio indica che l'impostazione TargetNamespace per due o più schemi XML nelle descrizioni di servizi fornite è identica. Poiché TargetNamespace deve essere un identificatore univoco di un determinato documento XML, nel caso specifico uno schema XML, lo strumento Wsdl.exe presume che i due schemi XML siano identici e pertanto crea una classe proxy solo per uno degli schemi. Se questo non fosse il risultato desiderato, l'impostazione TargetNamespace per ogni schema XML deve essere modificata e impostata su un URI univoco. La modifica dell'impostazione TargetNamespace dipende dall'origine degli schemi XML in questione.

Vedere anche

Generazione di client dei servizi Web XML | Individuazione di servizi Web XML | Creazione di client per servizi Web XML | Accesso a servizi Web XML esistenti creati con ASP.NET | Comunicazione asincrona con servizi Web XML | Accesso ai servizi Web XML da un browser