Tutorial: creación de un servicio web personalizado

Artículo
02/01/2010

En esta tarea de programación se proporciona una introducción a la creación de un servicio web personalizado que funciona en el contexto de Windows SharePoint Services 3.0. Muestra paso a paso el proceso de creación de un servicio web simple "Hello World" y, a continuación, muestra cómo modificar el servicio para que implemente el modelo de objetos de servidor de Windows SharePoint Services 3.0 para devolver datos de lista y de sitio.

Pasos básicos para crear un servicio web

Cree un servicio web ASP.NET en Microsoft Visual Studio 2005.
Cree una biblioteca de clases en un servicio web que defina la lógica de programación para el servicio web.
Genere y edite un archivo de detección estático y un archivo de Lenguaje de descripción de servicios web (WSDL).
Implemente el archivo de servicio web para el directorio _vti_bin.
Cree una aplicación cliente para consumir el servicio web.

Creación de un servicio web ASP.NET en Visual Studio

El primer paso es crear un sitio de servicio web ASP.NET en Visual Studio 2005.

Para crear un servicio Web ASP.NET

En Visual Studio, haga clic en Archivo, seleccione Nuevo y, a continuación, seleccione Sitio web.
En el cuadro Plantillas del cuadro de diálogo Nuevo sitio Web, seleccione Servicio Web ASP.NET, seleccione Sistema de archivos en el cuadro Ubicación, seleccione un lenguaje de programación y una ubicación para el proyecto y, a continuación, haga clic en Aceptar.
En la nueva solución del servicio web, cree un proyecto de biblioteca de clases diferente para incluir la lógica del servicio web. Para crear un proyecto, haga clic en Archivo, seleccione Nuevo y, a continuación, seleccione Proyecto.
En el cuadro de diálogo Nuevo proyecto, seleccione un idioma en el cuadro Tipo de proyecto, seleccione Biblioteca de clases en el cuadro Plantillas , proporcione un nombre y una ubicación para el proyecto, seleccione Agregar a la solución en el cuadro Solución y a continuación, haga clic en Aceptar.
Agregue una referencia al espacio de nombres System.Web.Services en el proyecto de biblioteca de clases. Haga clic con el botón secundario sobre el proyecto en el Explorador de soluciones, haga clic en Agregar referencia, seleccione System.Web.Services en el cuadro de diálogo Agregar referencia y a continuación haga clic en Aceptar.
Reemplace el archivo de clase predeterminado en el proyecto de biblioteca de clases por el archivo de clase de servicio predeterminado proporcionado por Visual Studio en la carpeta App_Code del servicio web.

Para reemplazar el archivo de clase por el archivo de clase de servicio
1. En el Explorador de soluciones, arrastre Service.cs o Service.vb hacia el nodo superior del proyecto de biblioteca de clases.
2. Elimine el archivo Class1.cs o Class1.vb y elimine también el archivo Service.cs o Service.vb que queda en la carpeta App_Code.
Cree un nombre seguro para la biblioteca de clases:
1. En el Explorador de soluciones, haga clic con el botón secundario en el proyecto de biblioteca de clases y, a continuación, haga clic en Propiedades.
2. En el cuadro de diálogo Propiedades, haga clic en Firma, seleccione Firmar el ensamblado y, a continuación, seleccione <Nuevo> en la lista Seleccione un archivo de clave de nombre seguro.
3. En el cuadro de diálogo Crear clave de nombre seguro, proporcione un nombre de archivo para la clave, desactive la casilla Proteger mi archivo de clave mediante contraseña y, a continuación, haga clic en Aceptar.
Para generar tan sólo el proyecto de biblioteca de clases, haga clic con el botón secundario en el proyecto en el Explorador de soluciones y, a continuación, haga clic en Generar.
Para agregar su ensamblado a la memoria caché de ensamblados global (GAC), puede arrastrar el ensamblado al directorio %windows%\assembly mediante 2 instancias del Explorador de Windows o puede usar la utilidad de línea de comandos gacutil.exe que se instala con el SDK de Microsoft .NET Framework 2.0.

Para usar gacutil.exe para copiar la DLL de biblioteca de clases en la GAC
1. Para abrir un símbolo del sistema de Visual Studio, haga clic en Inicio, seleccione Todos los programas, seleccione Microsoft Visual Studio 2005, seleccione Herramientas de Visual Studio y, a continuación, haga clic en Símbolo del sistema de Visual Studio 2005.
2. En el símbolo del sistema, escriba el siguiente comando y presione Entrar:
  
  gacutil.exe -if "<Full file system path to DLL>".
Ahora ya puede cambiar la información del ensamblado en el archivo predeterminado Service.asmx del servicio web por la información de la DLL desde la GAC. Para obtener información de la GAC, abra el directorio %windows%\assembly en el Explorador de Windows, haga clic con el botón secundario en su ensamblado y, a continuación, haga clic en Propiedades.
Para abrir Service.asmx en el Explorador de soluciones, haga clic con el botón secundario en el archivo y haga clic en Abrir.
Quite el atributo CodeBehind de la directiva de página en Service.asmx y modifique el contenido del atributo Class de forma que la directiva coincida con el formato siguiente, donde el nombre del ensamblado "MyServiceAssembly" y el token de clave pública son valores especificados en el cuadro de diálogo Propiedades que abrió en el Paso 10:
```
<%@ WebService Language="C#" Class="Service, MyServiceAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=8f2dca3c0f2d0131" %>
```
En Visual Basic, incluya el espacio de nombres para identificar la clase, por ejemplo, Class="MyServiceNamespace.Service, MyServiceAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=8f2dca3c0f2d0131".
Cambie el nombre del archivo .asmx del modo correspondiente y guarde los cambios.

Generación y modificación de archivos estáticos WSDL y de detección

Para proporcionar la detección y la descripción para el servicio web personalizado, debe crear un archivo .disco y un archivo .wsdl. Debido a que Windows SharePoint Services virtualiza las direcciones URL (por ejemplo, http://MyServer/MySite/MySubsite se convierte en http://MyServer), no puede usar archivos .disco y .wsdl generados automáticamente por ASP.NET. En su lugar, debe crear una página .disco y una página ASPX .wsdl que proporcionen la redirección necesaria y mantengan la virtualización.

Puede usar ASP.NET para generar los archivos .disco y .wsdl mediante el alojamiento temporal del servicio web en un directorio virtual, como /_layouts y, a continuación, usar la herramienta de detección de servicios web (Disco.exe) de .NET Framework para obtener los archivos generados.

Para generar los archivos estáticos WSDL y de detección

En el Explorador de Windows, copie el archivo .asmx del servicio web en \\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS.
Ejecute Disco.exe en el símbolo del sistema del directorio LAYOUTS para generar los archivos .disco y .wsdl. Ejecute un comando con el formato siguiente para generar los archivos en \LAYOUTS:

disco http://MyServer/_layouts/MyCustomWebService.asmx

Para registrar los espacios de nombres del modelo de objetos de Windows SharePoint Services, abra los archivos .disco y .wsdl y reemplace la instrucción de procesamiento XML de apertura, <?xml version="1.0" encoding="utf-8"?>, por instrucciones como las siguientes:

<%@ Page Language="C#" Inherits="System.Web.UI.Page" %> 
<%@ Assembly Name="Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %> 
<%@ Import Namespace="Microsoft.SharePoint.Utilities" %> 
<%@ Import Namespace="Microsoft.SharePoint" %>
<% Response.ContentType = "text/xml"; %>

En el archivo .disco, modifique la referencia de contrato y las etiquetas de dirección SOAP para sean como en el siguiente ejemplo, en el cual se reemplazan las rutas de acceso a los literales por las rutas de acceso a código generadas mediante la clase Microsoft.SharePoint.Utilities.SPHttpUtility. Además, en el ejemplo se reemplaza el nombre del método especificado en el atributo binding:

<contractRef ref=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(SPWeb.OriginalBaseUrl(Request) + "?wsdl"),Response.Output); %> 
docRef=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(SPWeb.OriginalBaseUrl(Request)),Response.Output); %> 
xmlns="https://schemas.xmlsoap.org/disco/scl/" />
<soap address=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(SPWeb.OriginalBaseUrl(Request)),Response.Output); %> 
xmlns:q1="http://tempuri.org/" binding="q1:HelloWorld" xmlns="https://schemas.xmlsoap.org/disco/soap/" />
<soap address=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(SPWeb.OriginalBaseUrl(Request)),Response.Output); %> 
xmlns:q2="http://tempuri.org/" binding="q2:ServiceSoap12" xmlns="https://schemas.xmlsoap.org/disco/soap/" />

En el archivo .wsdl, realice la siguiente sustitución similar para la dirección SOAP especificada:

<soap:address location=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(SPWeb.OriginalBaseUrl(Request)),Response.Output); %> />

Cambie el nombre de ambos archivos en los formatos respectivos MyCustomWebServicedisco.aspx y MyCustomWebServicewsdl.aspx para que el servicio se pueda detectar con Windows SharePoint Services.

Copia de los archivos de servicio web en el directorio _vti_bin

El directorio virtual _vti_bin se asigna físicamente al directorio unidad_local:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\ISAPI, el cual contiene los archivos predeterminados de servicio web usados en Windows SharePoint Services. Copie los archivos nuevos MyCustomWebServicewsdl.aspx y MyCustomWebServicedisco.aspx, y también los archivos MyCustomWebService.asmx, en la carpeta ISAPI.

En el directorio _vti_bin, un servicio web ofrece su funcionalidad al sitio especificado al agregar una referencia web para el servicio.

Para comprobar si el servicio web personalizado se puede detectar, vaya a http://MyServer/_vti_bin/MyCustomWebService.asmx.

Inclusión del nuevo servicio web en spdisco.aspx

Para que el servicio web se pueda detectar en Visual Studio como un servicio web junto con los servicios web predeterminados de Windows SharePoint Services, abra el archivo spdisco.aspx ubicado en \Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\ISAPI, agregue el siguiente código y especifique el archivo .asmx para el servicio web.

<contractRef ref=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(spWeb.Url + "/_vti_bin/MyCustomWebService.asmx?wsdl"), Response.Output); %> 
docRef=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(spWeb.Url + "/_vti_bin/MyCustomWebService.asmx"), Response.Output); %> 
xmlns=" https://schemas.xmlsoap.org/disco/scl/ " />
<discoveryRef ref=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(spWeb.Url + "/_vti_bin/MyCustomWebService.asmx?disco"),Response.Output); %> 
xmlns="https://schemas.xmlsoap.org/disco/" />

Creación de una aplicación de Windows para el consumo del servicio web personalizado

Una vez copiados los archivos de servicios web en el directorio _vti_bin, el siguiente paso es crear una aplicación de Windows para el servicio web personalizado.

Para crear una aplicación de Windows para el consumo del servicio web

Abra Visual Studio 2005 y en el menú Archivo, seleccione Nuevo y, a continuación, haga clic en Proyecto.
En el cuadro de diálogo Nuevo proyecto, seleccione Visual C# o Visual Basic y, a continuación, seleccione la plantilla Aplicación para Windows.
Escriba un nombre para la aplicación en el cuadro Nombre, especifique una ubicación para los archivos del proyecto en el cuadro Ubicación y, a continuación, haga clic en Aceptar.
En el Explorador de soluciones, haga clic con el botón secundario en el proyecto y a continuación haga clic en Agregar referencia web.
En la barra de direcciones del explorador Agregar referencia Web, escriba la dirección URL para el sitio al cual se aplica el servicio de la siguiente manera y, a continuación, presione ENTRAR:

https://Server_Name/[sites/][Site_Name/]_vti_bin/MyCustomWebService.asmx
Haga clic en Agregar referencia para descargar el contrato de servicio del servicio web.
Abra Form1 en la vista de diseño, muestre el Cuadro de herramientas y, a continuación, arrastre un botón al formulario.

Haga doble clic en el control Button1 en Form1 para mostrar el archivo de código subyacente en el editor de código y agregue el siguiente código que llama al método personalizado.

Dim MyCustomService As New Web_Reference_Folder.MyServiceClass()
MyCustomService.UseDefaultCredentials = True
MessageBox.Show(MyCustomService.HelloWorld())

                            Web_Reference_Folder.MyServiceClass MyCustomService = new Web_Reference_Folder.MyServiceClass();
MyCustomService.UseDefaultCredentials = true;
MessageBox.Show(MyCustomService.HelloWorld());

Presione F5 para compilar y ejecutar el proyecto, y ver un cuadro de mensaje que muestra "Hello World".

Implementación del modelo de objetos de Windows SharePoint Services

Ahora ya puede probar los tipos y miembros del modelo de objetos de Windows SharePoint Services en la biblioteca de clases de su servicio web.

Para implementar del modelo de objetos de Windows SharePoint Services

Agregue una referencia al ensamblado Microsoft.SharePoint. Haga clic con el botón secundario sobre el proyecto de biblioteca de clases en el Explorador de soluciones , haga clic en Agregar referencia, seleccione Windows SharePoint Services y, a continuación, haga clic en Aceptar.
En el archivo de proyecto Service.cs o Service.vb, debe importar los espacios de nombres correspondientes en el modelo de objetos. Por ejemplo, para usar los tipos y miembros de los espacios de nombres Microsoft.SharePoint y Microsoft.SharePoint.Utilities, agregue las siguientes directivas:
```
Imports Microsoft.SharePoint
Imports Microsoft.SharePoint.Utilities
```
```
using Microsoft.SharePoint;
using Microsoft.SharePoint.Utilities;
```
Cambie el nombre del método en Service.cs o Service.vb. Por ejemplo, cambie el nombre HelloWorld a GetSiteListCount.
Agregue el siguiente código para mostrar el nombre del sitio web y el número de las listas que contiene.
```
Dim myWebSite As SPWeb = SPContext.Current.Web
Dim lists As SPListCollection = myWebSite.Lists

Return myWebSite.Title + " contains " + lists.Count.ToString() + 
" lists."
```
```
SPWeb myWebSite = SPContext.Current.Web;
SPListCollection lists = myWebSite.Lists;

return (myWebSite.Title + " contains " + lists.Count.ToString() + 
" lists.");
```
Nota

Si el código modifica los datos de Windows SharePoint Services de alguna forma, es posible que necesite permitir que se realicen actualizaciones no seguras en el sitio web. Puede hacer esto mediante el establecimiento de la propiedad AllowUnsafeUpdates.
Para volver a generar la DLL de la biblioteca de clases y copiarla en la GAC, repita los pasos 8 y 9 de "Para crear un servicio Web ASP.NET".
Restablezca Internet Information Services (IIS) para que los cambios en la DLL surtan efecto.
Para generar nuevas versiones de los archivos .disco y .wsdl, repita los pasos de "Para generar los archivos estáticos WSDL y de detección", pero cambie el nombre de enlace del método según corresponda en el archivo .disco (por ejemplo, a GetSiteListCount).
Copie las nuevas versiones de los archivos MyCustomWebServicedisco.aspx y MyCustomWebServicewsdl.aspx en la carpeta ISAPI.
Abra la aplicación para Windows creada anteriormente, elimine la referencia del servicio web anterior para el ejemplo Hello World, cambie el nombre de método según corresponda y agregue una referencia web nueva al servicio web revisado.
Presione F5 para compilar y ejecutar el proyecto, y para ver el cuadro de mensaje que muestra el nombre del sitio web y el número de listas que contiene.