Indice dei contenuti
Come abbiamo recentemente scritto qualche settimana fa in questo articolo, il modo più appropriato per creare un Web Service SOAP su ASP.NET è, ancora a fine 2016, quello di utilizzare il framework WCF (acronimo per Windows Communication Foundation): si tratta di una architettura che, nonostante gli anni comincino a farsi sentire, resta di gran lunga più versatile rispetto alle ormai più che obsolete pagine ASMX.
Nell'articolo precedente, oltre a risolvere un problema specifico legato alla configurazione di un servizio WCF su IIS8, abbiamo speso qualche minuto a ricordare le caratteristiche dell'architettura, presentata in pompa magna da Microsoft nell'ottobre 2008 e poi allontanata dai riflettori per lasciare spazio al paradigma Web API, adatto però solo ai Web Service REST. In questo articolo ci dedicheremo a riassumere i passaggi necessari per creare un Web Service SOAP partendo da zero utilizzando le ultime versioni degli strumenti necessari, ovvero: Visual Studio 2015 e Internet Information Services 8.
Creare un progetto WCF
La prima cosa da fare è lanciare Visual Studio e creare un nuovo progetto: la versione 2015 fornisce due template adatti allo scopo: il primo, denominato WCF Service Library, consente di creare una libreria separata da utilizzare in altri progetti: il secondo, WCF Service Application, contiene anche gli endpoint necessari per gestire le chiamate SOAP tramite web.
Nel nostro caso andremo a utilizzare quest'ultimo: il nome della nostra applicazione di esempio sarà MyWCF.
Una volta premuto OK, Visual Studio provvederà a creare una soluzione e un progetto contenente un Web Service di esempio, Service1.svc, e relativa interfaccia IService1.cs, con due metodi già funzionanti: GetData, che può accettare una richiesta SOAP contenente un input generico di tipo Int32, e GetDataUsingDataContract, che richiede invece un input strutturato.
WCF Test Client
Possiamo verificare il funzionamento di entrambi i metodi lanciando l'applicazione in Debug Mode: Visual Studio provvederà a metterci a disposizione uno strumento apposito - il WCF Test Client - mediante il quale potremo effettuare delle richieste SOAP e visualizzare i risultati.
IMPORTANTE: Ricordate di selezionare il file Service1.svc nel Solution Explorer prima di lanciare l'applicazione in Debug, altrimenti il WCF Test Client non verrà inizializzato.
A quanto pare, il più è fatto! Il nostro Web Service funziona, tutto quello che dobbiamo fare è implementare i metodi che ci interessano, in aggiunta o in sostituzione di quelli di esempio.
Aggiunta di un metodo GetToken
Proviamo ora ad aggiungere un classico metodo GetToken, che accetta in input due campi di tipo string - un username e una password - e restituisce un Guid in caso di autenticazione avvenuta con successo oppure una stringa vuota in caso di errore. Ovviamente, non avendo un Database di utenti a disposizione, ci limiteremo a realizzare un codice di esempio, dando per scontato che l'implementazione effettiva sarà più complessa: del resto, quello che ci interessa ora è comprendere il funzionamento dell'architettura WCF.
Apriamo dunque il file IService1.cs e definiamo il nostro metodo:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
[ServiceContract] public interface IService1 { [OperationContract] string GetData(int value); [OperationContract] CompositeType GetDataUsingDataContract(CompositeType composite); // TODO: Add your service operations here [OperationContract] string GetToken(string userName, string password); } |
Rispetto al codice già presente abbiamo aggiunto solo le ultime due righe, che definiscono per l'appunto le caratteristiche del metodo che vogliamo aggiungere: l'attributo [OperationContract] è di particolare importanza, poiché contrassegna il metodo come operazione da esporre a livello di Web Service. Andiamo ora ad aggiungere l'implementazione effettiva all'interno del file Service1.svc nel seguente modo:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
/// <summary> /// Retrieve a non-permanent token to be used for any subsequent WS call. /// </summary> /// <param name="userName">a valid userName</param> /// <param name="password">the corresponding password</param> /// <returns>a GUID if authentication succeeds, or string.Empty if something goes wrong</returns> public string GetToken(string userName, string password) { if (userName == "testUser" && password == "testPassword") { // Authentication Successful return Guid.NewGuid().ToString(); } else { // Authentication Failed return string.Empty; } } |
Come possiamo vedere, il codice è estremamente semplice: ci limitiamo a effettuare un controllo dei dati inviati dalla richiesta SOAP: in caso corrispondano a un account valido restituiamo un Guid, altrimenti una stringa vuota. Come già detto, in un real-case scenario avremmo certamente a disposizione un Database da utilizzare per svolgere le due operazioni che abbiamo simulato: recuperare l'accoppiata username/password corrispondente alla request SOAP ricevuta e, in caso di autenticazione avvenuta, memorizzare il token da inviare nella response che andremo a restituire, così da poterlo recuperare e verificare successivamente.
Per provare il nostro nuovo servizio non dobbiamo far altro che lanciare la nostra applicazione in Debug Mode e utilizzare il WCF Test Tool per inserire i valori di esempio che abbiamo impostato come validi: testUser e testPassword. Se abbiamo fatto tutto correttamente, vedremo il seguente risultato:
Una volta premuto il pulsante Invoke, potremo verificare il corretto esito del nostro Response nella sezione in basso del WCF Test Tool. Nella screenshot di cui sopra il Guid è stato generato, segno che tutto funziona correttamente.
Impostare il WSDL Binding Type
Come probabilmente già sapete se lavorate con i Web Service SOAP, esistono quattro possibili Binding Type a cui il nostro WSDL può conformarsi: le quattro tipologie sono descritte efficacemente in questo articolo della IBM, il cui senso si può riassumere nella seguente citazione:
A WSDL document describes a Web service. A WSDL binding describes how the service is bound to a messaging protocol, particularly the SOAP messaging protocol. A WSDL SOAP binding can be either a Remote Procedure Call (RPC) style binding or a document style binding. A SOAP binding can also have an encoded use or a literal use.
L'architettura WCF si occupa di generare il WSDL automaticamente, dandoci nel contempo la possibilità di definire quale Binding Type utilizzare: tale scelta può essere effettuata utilizzando l'attributo [XmlSerializerFormat], che può essere assegnato sia a livello generale - ovvero immediatamente sopra alla definizione dell'interfaccia - che per ciascun singolo metodo. Questi i valori ammessi, corrispondenti rispettivamente alle quattro modalità possibili:
Rpc/Encoded
|
1 |
[XmlSerializerFormat(Style = OperationFormatStyle.Rpc, Use = OperationFormatUse.Encoded)] |
Rpc/Literal
|
1 |
[XmlSerializerFormat(Style = OperationFormatStyle.Rpc, Use = OperationFormatUse.Literal)] |
Document/Encoded
|
1 |
[XmlSerializerFormat(Style = OperationFormatStyle.Document, Use = OperationFormatUse.Encoded)] |
Document/Literal
|
1 |
[XmlSerializerFormat(Style = OperationFormatStyle.Document, Use = OperationFormatUse.Literal)] |
Visto che stiamo modificando gli attributi del file IService.cs, possiamo approfittare per definire un nostro namespace che andrà a sostituire il classico tempuri.org valorizzando opportunamente la proprietà Namespace dell'attributo ServiceContract:
|
1 |
[ServiceContract(Name = "Service", Namespace = "http://www.MyWCF.com/")] |
Questa modifica si rifletterà automaticamente sulle endpoint URL di tutti i nostri metodi, che saranno aggiornate di conseguenza, rispettando la convenzione standerd dei Web Service: Namespace/ClassName/MethodName, ovvero (nel caso di cui sopra): http://www.MyWCF.com/Service/GetToken .
Impostare gli indirizzi degli Endpoint
Nel caso in cui la convenzione Namespace/ClassName/MethodName ci andasse stretta, abbiamo la possibilità di personalizzare l'endpoint URL valorizzando un paio di proprietà dell'attributo [OperationContract], già presente all'interno dell'interfaccia IService1.cs per ciascuno dei nostri metodi, nel seguente modo:
|
1 2 |
[OperationContract(Action = "https://myurl.com/OtherName/GetToken", ReplyAction = "https://myurl.com/OtherName/GetToken")] string GetToken(string userName, string password); |
Ovviamente, nel caso in cui volessimo utilizzare delle URL personalizzate, sarà poi necessario gestire il corretto instradamento di queste request a livello di server-side Routing. Per far questo, sarà sufficiente dotare il nostro progetto di una Global Application Class, più nota come Global.asax, e definire una o più Route a livello di Application_Start nel seguente modo:
|
1 2 3 4 5 6 |
protected void Application_Start(object sender, EventArgs e) { RouteTable.Routes.Add(new ServiceRoute( "OtherName", new ServiceHostFactory(), typeof(MyWCF.Service1)) ); } |
... E questo è tutto: felice Web Service!
P.S.: Nel caso in cui abbiate problemi legati alla comparsa di errori HTTP 404 al momento della pubblicazione in produzione su IIS, non dimenticatevi di leggere il già citato articolo che spiega come ovviare a tale problematica.
