Contract-First web services con Visual Studio 2008
Índice
- Introducción
- Descriptor del contrato
- Implementación con Visual Studio 2008. WSCF.blue
- Probar el web service con soapUI
- Conclusión
Introducción
En el diseño y desarrollo de servicios web podemos utilizar dos aproximaciones:
- Dirigido por contrato, o Contract-First. Primero se describen las funcionalidades del servicio web en cuanto a su interfaz, semántica y aspectos administrativos de la invocación, siendo la especificación WSDL el estándar. El WSDL, como documento XML, puede ser parseado por una herramienta para facilitar la implementación del web service proveedor o consumidor.
- Contract-Last, en el que primero se implementa el servicio web en un determinado lenguaje y posteriormente se genera un WSDL que lo describa.
Cada cual tiene sus ventajas e inconvenientes [1] [2] [3]. En este tutorial veremos la primera de las dos opciones, implementando en C# un servicio web proveedor. Utilizaremos las siguientes herramientas:
- Windows Vista Home Edition SP2, C2D@1.5, 3GB Ram
- Microsoft Visual Studio 2008 Professional SP1
- Microsoft .NET Framework 3.5 SP1
- thinktercure WSCF.blue V1 Final (1.0.5) (*)
- soapUI 3.0.1
(*) En el momento de escribir este tutorial no existe una versión para Visual Studio 2008 Express Edition
El código fuente de este tutorial puede descargarse aquí: wsEncriptacion_adictosaltrabajo.zip
Descriptor del contrato
Vamos a trabajar con un web service de encriptación mediante Triple-DES y MD5 que ofrece dos operaciones :
- encriptar. Recibe tres tipos simples: la cadena de texto en claro, la clave de encriptación y un flag para el uso o no de hashing. Devuelve la cadena de texto encriptada.
- desencriptar. Recibe un tipo complejo compuesto por tres tipos simples: la cadena de texto encriptada, la clave utilizada en la encriptación y el flag para indicar el uso de hashing. Devuelve la cadena de texto desencriptada.
El uso de tipos simples o complejos es una cuestión de diseño, y en nuestro caso lo hacemos así para ampliar la cobertura de capacidades de WSCF.blue.
Definición de los tipos del documento con XML Schema
La definición del tipo de datos complejo lo implementamos mediante un XML Schema. Se muestra a continuación, y puede descargarse aquí: cryptoSchema.xsd
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
<?xml version=<code class="quote">"1.0"</code> encoding=<code class="quote">"UTF-8"</code>?> <!-- cryptoSchema.xsd Tutorial: Contract-<code class="keyword">First</code> web services con Visual Studio 2008 www.adictosaltrabajo.com - Ivan Garcia Puebla --> <xsd:<code class="keyword">schema</code> xmlns:xsd=<code class="quote">"http://www.w3.org/2001/XMLSchema" targetNamespace=<code class="quote">"http://tutorial.adictosaltrabajo.com/schema/cryptoSchema" xmlns:tns=<code class="quote">"http://tutorial.adictosaltrabajo.com/schema/cryptoSchema" elementFormDefault=<code class="quote">"qualified"</code>> <xsd:complexType name=<code class="quote">"datosDesencriptar"</code>> <xsd:<code class="keyword">sequence</code>> <xsd:element name=<code class="quote">"encriptado"</code> <code class="keyword">type</code>=<code class="quote">"xsd:string"</code>></xsd:element> <xsd:element name=<code class="quote">"clave"</code> <code class="keyword">type</code>=<code class="quote">"xsd:string"</code>></xsd:element> <xsd:element name=<code class="quote">"usarHashing"</code> <code class="keyword">type</code>=<code class="quote">"xsd:boolean"</code>></xsd:element> </xsd:<code class="keyword">sequence</code>> </xsd:complexType> </xsd:<code class="keyword">schema</code>> |
Definición del contrato con WSDL
Implementamos el contrato del web service en un descriptor WSDL concreto. Utilizaremos el Schema anterior, SOAP sobre HTTP, y el resto de detalles se muestran a continuación:
descriptor cryptoService.wsdl
El fuente del fichero puede descargarse aquí: cryptoService.wsdl.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 |
<?xml version=<code class="quote">"1.0"</code> encoding=<code class="quote">"UTF-8"</code>?> <!-- cryptoServiceWSDL.wsdl Tutorial: Contract-<code class="keyword">First</code> web services con Visual Studio 2008 www.adictosaltrabajo.com - Ivan Garcia Puebla --> <definitions name=<code class="quote">"cryptoServiceWSDL" targetNamespace=<code class="quote">"http://tutorial.adictosaltrabajo.com/wsdl/cryptoServiceWSDL" xmlns=<code class="quote">"http://schemas.xmlsoap.org/wsdl/" xmlns:wsdl=<code class="quote">"http://schemas.xmlsoap.org/wsdl/" xmlns:xsd=<code class="quote">"http://www.w3.org/2001/XMLSchema" xmlns:tns=<code class="quote">"http://tutorial.adictosaltrabajo.com/wsdl/cryptoServiceWSDL" xmlns:ns=<code class="quote">"http://tutorial.adictosaltrabajo.com/schema/cryptoSchema" xmlns:soap=<code class="quote">"http://schemas.xmlsoap.org/wsdl/soap/"</code>> <types> <xsd:<code class="keyword">schema</code> targetNamespace=<code class="quote">"http://tutorial.adictosaltrabajo.com/wsdl/cryptoServiceWSDL"</code>> <xsd:import namespace=<code class="quote">"http://tutorial.adictosaltrabajo.com/schema/cryptoSchema" schemaLocation=<code class="quote">"cryptoSchema.xsd"</code>/> </xsd:<code class="keyword">schema</code>> </types> <message name=<code class="quote">"encriptarRequest"</code>> <part name=<code class="quote">"original"</code> <code class="keyword">type</code>=<code class="quote">"xsd:string"</code>/> <part name=<code class="quote">"clave"</code> <code class="keyword">type</code>=<code class="quote">"xsd:string"</code>/> <part name=<code class="quote">"usarHashing"</code> <code class="keyword">type</code>=<code class="quote">"xsd:boolean"</code>/> </message> <message name=<code class="quote">"encriptarResponse"</code>> <part name=<code class="quote">"resultado"</code> <code class="keyword">type</code>=<code class="quote">"xsd:string"</code>/> </message> <message name=<code class="quote">"desencriptarRequest"</code>> <part name=<code class="quote">"datosDesencriptar"</code> <code class="keyword">type</code>=<code class="quote">"ns:datosDesencriptar"</code>/> </message> <message name=<code class="quote">"desencriptarResponse"</code>> <part name=<code class="quote">"resultado"</code> <code class="keyword">type</code>=<code class="quote">"xsd:string"</code>/> </message> <portType name=<code class="quote">"cryptoServiceWSDLPortType"</code>> <<code class="keyword">operation</code> name=<code class="quote">"encriptar"</code>> <<code class="keyword">input</code> name=<code class="quote">"inputEncriptar"</code> message=<code class="quote">"tns:encriptarRequest"</code>/> <<code class="keyword">output</code> name=<code class="quote">"outputEncriptar"</code> message=<code class="quote">"tns:encriptarResponse"</code>/> </<code class="keyword">operation</code>> <<code class="keyword">operation</code> name=<code class="quote">"desencriptar"</code>> <<code class="keyword">input</code> name=<code class="quote">"inputDesencriptar"</code> message=<code class="quote">"tns:desencriptarRequest"</code>/> <<code class="keyword">output</code> name=<code class="quote">"outputDesencriptar"</code> message=<code class="quote">"tns:desencriptarResponse"</code>/> </<code class="keyword">operation</code>> </portType> <binding name=<code class="quote">"cryptoServiceWSDLBinding"</code> <code class="keyword">type</code>=<code class="quote">"tns:cryptoServiceWSDLPortType"</code>> <soap:binding style=<code class="quote">"rpc"</code> transport=<code class="quote">"http://schemas.xmlsoap.org/soap/http"</code>/> <<code class="keyword">operation</code> name=<code class="quote">"encriptar"</code>> <soap:<code class="keyword">operation</code>/> <<code class="keyword">input</code> name=<code class="quote">"inputEncriptar"</code>> <soap:body use=<code class="quote">"literal" namespace=<code class="quote">"http://tutorial.adictosaltrabajo.com/wsdl/cryptoServiceWSDL"</code>/> </<code class="keyword">input</code>> <<code class="keyword">output</code> name=<code class="quote">"outputEncriptar"</code>> <soap:body use=<code class="quote">"literal" namespace=<code class="quote">"http://tutorial.adictosaltrabajo.com/wsdl/cryptoServiceWSDL"</code>/> </<code class="keyword">output</code>> </<code class="keyword">operation</code>> <<code class="keyword">operation</code> name=<code class="quote">"desencriptar"</code>> <soap:<code class="keyword">operation</code>/> <<code class="keyword">input</code> name=<code class="quote">"inputDesencriptar"</code>> <soap:body use=<code class="quote">"literal" namespace=<code class="quote">"http://tutorial.adictosaltrabajo.com/wsdl/cryptoServiceWSDL"</code>/> </<code class="keyword">input</code>> <<code class="keyword">output</code> name=<code class="quote">"outputDesencriptar"</code>> <soap:body use=<code class="quote">"literal" namespace=<code class="quote">"http://tutorial.adictosaltrabajo.com/wsdl/cryptoServiceWSDL"</code>/> </<code class="keyword">output</code>> </<code class="keyword">operation</code>> </binding> <service name=<code class="quote">"cryptoServiceWSDLService"</code>> <port name=<code class="quote">"cryptoServiceWSDLPort"</code> binding=<code class="quote">"tns:cryptoServiceWSDLBinding"</code>> <soap:address location=<code class="quote">"http://localhost:8080/cryptoService"</code>/> </port> </service> </definitions> |
Implementación con Visual Studio 2008. WSCF.blue
A partir del descriptor generaremos los stubs en C# del servicio que ofrezca las dos operaciones; posteriormente damos cuerpo al webservice y añadimos la lógica de negocio. En .NET podemos hacerlo a través del plugin/add-in para Visual Studio 2008, WSCF.blue. En el MSDN hay un interesante artículo publicado, http://msdn.microsoft.com/en-us/magazine/ee335699.aspx, sobre Contract-First Web Services y WSCF.blue, e incluye el enlace http://se.ethz.ch/~meyer/publications/computer/contract.pdf al artículo original de Bertrand Meyer: Applying «Design by Contract», aparecido en el IEEE en 1992
Instalación de WSCF.blue
Descargamos el instalador del acceso Download de http://www.codeplex.com/WSCFblue/ y lo instalamos siguiendo el asistente, de manera habitual.
Crear el servicio e importar el contrato
En Visual Studio 2008 creamos un nuevo proyecto de tipo Web de Visual C#. Utilizaremos la plantilla: Aplicación de servicio web de ASP.NET y damos como nombre wsEncriptacion. Agregamos una nueva carpeta llamada wscfEncriptacion y a continuación nuestros WSDL y Schema:
Proyecto creado en Visual Studio 2008
Bien en el menú Herramientas | Web Services Contract-First o bien pulsando con el botón derecho sobre cryptoServiceWSDL.wsdl, accedemos a las funcionalidades de WSCF.blue y escogemos Generate Web Service Code:
Menú contextual de WSCF.blue
Establecemos las opciones de generación de código siguientes:
Generación de código con WSCF.blue
Como se observa en la imagen, hemos establecido las opciones siguientes:
- Server-side stub: vamos a generar el web service proveedor
- Format SOA Actions: determinamos que las acciones SOAP de cada operación del contrato sigan el formato estándar de contratos de web services: <namespace>/<service>/<operation>[Response]
- Separate files: cada tipo de dato del servicio web será generado en un fichero de C# distinto
- Adjust casing: los tipos de datos generados seguirán la notación de .NET
- Use synchronization context: el contexto determinará en qué hilo se ejecutará el web service
- Generate a regular service class …: permitiremos generar métodos en donde implementar la lógica del servicio
Estas opciones son expuestas a modo de ejemplo. Cada proyecto requerirá de la configuración más adecuada para sus propósitos. La documentación se encuentra en: https://www.thinktecture.com/
Pulsamos en Generate y en unos instantes se confirmará la ejecución correcta de la operación:
Código generado correctamente
En el explorador de soluciones podemos observar el código que ha sido generado:
Stubs generados del web service proveedor
Implementar el web service
La clase cryptoServiceWSDLPortType es la que finalmente alberga los métodos donde se implementará la lógica de negocio de nuestro servicio web. En su definición vemos que es una clase derivada de la interfaz IcryptoServiceWSDLPortType. En este tutorial implementaremos el fichero ASP web service, Service1.asmx, directamente con estos métodos. Para ello editamos el código de Service1.asmx y trasladamos el código de cryptoServiceWSDLPortType.cs de la siguiente manera.
- Los atributos de compilación de la clase cryptoServiceWSDLPortType los establecemos en la clase de Service1
- La clase Service1 la convertimos en derivada de IcryptoServiceWSDLPortType
- Los métodos encriptar y desencriptar de cryptoServiceWSDLPortType los copiamos como métodos públicos no virtuales en la clase de Service1 con el atributo [WebService]
Finalmente eliminamos de cada método la sentencia de lanzamiento de excepción y añadimos nuestra lógica de encriptación/desencriptación. En este caso me he basado en el post: http://www.csharper.net/blog/library_encrypt_and_decrypt_methods_using_tripledes_and_md5.aspx. En resumen, Service1.asmx.cs queda de la forma:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 |
using</code> System; using</code> System.Collections.Generic; using</code> System.Linq; using</code> System.Web; using</code> System.Web.Services; using</code> System.Text; using</code> System.Security.Cryptography; namespace</code> wsEncriptacion { /// <summary> /// Service1.asmx /// Tutorial: Contract-First web services con Visual Studio 2008 /// www.adictosaltrabajo.com - Ivan Garcia Puebla /// </summary> [WebService(<code class="keyword">Namespace</code> = <code class="quote">"http://tempuri.org/"</code>)] [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)] [System.ComponentModel.ToolboxItem(<code class="keyword">false</code>)] [System.ServiceModel.ServiceBehaviorAttribute(InstanceContextMode = System.ServiceModel.InstanceContextMode.PerCall, ConcurrencyMode = System.ServiceModel.ConcurrencyMode.Single)] public</code> <code class="keyword">class</code> Service1 : System.Web.Services.WebService, IcryptoServiceWSDLPortType { [WebMethod] public</code> OutputEncriptar Encriptar(InputEncriptar request) { string</code> textoAEncriptar = request.Encriptar.Original; string</code> clave = request.Encriptar.Clave; bool</code> usarHashing = request.Encriptar.UsarHashing; byte</code>[] keyArray; byte</code>[] toEncryptArray = UTF8Encoding.UTF8.GetBytes(textoAEncriptar); if</code> (usarHashing) { MD5CryptoServiceProvider hashmd5 = <code class="keyword">new</code> MD5CryptoServiceProvider(); keyArray = hashmd5.ComputeHash(UTF8Encoding.UTF8.GetBytes(clave)); hashmd5.Clear(); } else keyArray = UTF8Encoding.UTF8.GetBytes(clave); TripleDESCryptoServiceProvider tdes = <code class="keyword">new</code> TripleDESCryptoServiceProvider(); tdes.Key = keyArray; tdes.Mode = CipherMode.ECB; tdes.Padding = PaddingMode.PKCS7; ICryptoTransform cTransform = tdes.CreateEncryptor(); byte</code>[] resultArray = cTransform.TransformFinalBlock(toEncryptArray, 0, toEncryptArray.Length); string</code> textoEncriptado = Convert.ToBase64String(resultArray, 0, resultArray.Length); tdes.Clear(); OutputEncriptar output = <code class="keyword">new</code> OutputEncriptar(); EncriptarResponse response = <code class="keyword">new</code> EncriptarResponse(); response.Resultado = textoEncriptado; output.EncriptarResponse = response; return</code> output; } [WebMethod] public</code> OutputDesencriptar Desencriptar(InputDesencriptar request) { string</code> textoADesencriptar = request.Desencriptar.DatosDesencriptar.Encriptado; string</code> clave = request.Desencriptar.DatosDesencriptar.Clave; bool</code> usarHashing = request.Desencriptar.DatosDesencriptar.UsarHashing; byte</code>[] keyArray; byte</code>[] toEncryptArray = Convert.FromBase64String(textoADesencriptar); if</code> (usarHashing) { MD5CryptoServiceProvider hashmd5 = <code class="keyword">new</code> MD5CryptoServiceProvider(); keyArray = hashmd5.ComputeHash(UTF8Encoding.UTF8.GetBytes(clave)); hashmd5.Clear(); } else keyArray = UTF8Encoding.UTF8.GetBytes(clave); TripleDESCryptoServiceProvider tdes = <code class="keyword">new</code> TripleDESCryptoServiceProvider(); tdes.Key = keyArray; tdes.Mode = CipherMode.ECB; tdes.Padding = PaddingMode.PKCS7; ICryptoTransform cTransform = tdes.CreateDecryptor(); byte</code>[] resultArray = cTransform.TransformFinalBlock(toEncryptArray, 0, toEncryptArray.Length); string</code> textoDesencriptado = UTF8Encoding.UTF8.GetString(resultArray); tdes.Clear(); OutputDesencriptar output = <code class="keyword">new</code> OutputDesencriptar(); DesencriptarResponse response = <code class="keyword">new</code> DesencriptarResponse(); response.Resultado = textoDesencriptado; output.DesencriptarResponse = response; return</code> output; } } } |
Publicar y acceder al servicio
Iniciamos la depuración del proyecto y en la URL http://localhost:49193/Service1.asmx accedemos a la descripción del servicio web:
Probar el web service con soapUI
Para probar nuestro servicio utilizaremos soapUI (ejemplo de uso en el tutorial de Roberto Canales: Servicio Web con NetBeans 6 y prueba con SoapUI). El descriptor de nuestro servicio es http://localhost:49193/Service1.asmx?wsdl.
Creamos un mensaje SOAP request hacia la operación Encriptar con valores de ejemplo:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
<soap:Envelope xmlns:soap=<code class="quote">"http://www.w3.org/2003/05/soap-envelope" xmlns:tem=<code class="quote">"http://tempuri.org/"</code>> <soap:Header/> <soap:Body> <tem:Encriptar> <tem:request> <tem:Encriptar> <original><code class="keyword">Lorem ipsum dolor sit</code></original> <clave><code class="keyword">autentia2009</code></clave> <usarHashing><code class="keyword">true</code></usarHashing> </tem:Encriptar> </tem:request> </tem:Encriptar> </soap:Body> </soap:Envelope> |
y obtenemos como mensaje SOAP response:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
<soap:Envelope xmlns:soap=<code class="quote">"http://www.w3.org/2003/05/soap-envelope" xmlns:xsi=<code class="quote">"http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd=<code class="quote">"http://www.w3.org/2001/XMLSchema"</code>> <soap:Body> <EncriptarResponse xmlns=<code class="quote">"http://tempuri.org/"</code>> <EncriptarResult> <EncriptarResponse> <resultado xmlns=<code class="quote">""</code>><code class="keyword">m2K6Pf20MrNvX3uKR1e54KqpzLxnHmR0</code></resultado> </EncriptarResponse> </EncriptarResult> </EncriptarResponse> </soap:Body> </soap:Envelope> |
Realizamos la operación inversa, desencriptando el resultado anterior. El mensaje SOAP request será:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
<soap:Envelope xmlns:soap=<code class="quote">"http://www.w3.org/2003/05/soap-envelope" xmlns:tem=<code class="quote">"http://tempuri.org/" xmlns:cry=<code class="quote">"http://tutorial.adictosaltrabajo.com/schema/cryptoSchema"</code>> <soap:Header/> <soap:Body> <tem:Desencriptar> <tem:request> <tem:Desencriptar> <datosDesencriptar> <cry:encriptado><code class="keyword">m2K6Pf20MrNvX3uKR1e54KqpzLxnHmR0</code></cry:encriptado> <cry:clave><code class="keyword">autentia2009</code></cry:clave> <cry:usarHashing><code class="keyword">true</code></cry:usarHashing> </datosDesencriptar> </tem:Desencriptar> </tem:request> </tem:Desencriptar> </soap:Body> </soap:Envelope> |
El mensaje de respuesta obtenido concuerda con el esperado:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
<soap:Envelope xmlns:soap=<code class="quote">"http://www.w3.org/2003/05/soap-envelope" xmlns:xsi=<code class="quote">"http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd=<code class="quote">"http://www.w3.org/2001/XMLSchema"</code>> <soap:Body> <DesencriptarResponse xmlns=<code class="quote">"http://tempuri.org/"</code>> <DesencriptarResult> <DesencriptarResponse> <resultado xmlns=<code class="quote">""</code>><code class="keyword">Lorem ipsum dolor sit</code></resultado> </DesencriptarResponse> </DesencriptarResult> </DesencriptarResponse> </soap:Body> </soap:Envelope> |
Nuestro web service ha sido implementado correctamente partiendo de la descripción de un contrato.
Conclusión
En el Microsoft SDK existe la utilidad ServiceModel Metadata Utility Tool (Svcutil.exe) que permite asimismo generar las clases proxy del web service a partir del descriptor. Utilizar WSCF.blue no requiere de la instalación del SDK, no obstante, y aporta unas capacidades añadidas al propio IDE Visual Studio bastante interesantes para propósitos Contract-first.
