Uso de receptores de eventos en SharePoint Foundation 2010 (parte 1 de 2)
Resumen: los receptores de eventos en Microsoft SharePoint Foundation 2010 permiten personalizar código para responder cuando se producen acciones específicas en un objeto de SharePoint. Los ejemplos prácticos de este artículo muestran cómo usar eventos para mejorar las aplicaciones de SharePoint.
Última modificación: lunes, 09 de marzo de 2015
Hace referencia a: Business Connectivity Services | Open XML | SharePoint Designer 2010 | SharePoint Foundation 2010 | SharePoint Online | SharePoint Server 2010 | Visual Studio
En este artículo
Conceptos básicos sobre eventos en SharePoint Foundation 2010
Trabajar con eventos en SharePoint Foundation 2010
Uso de la plantilla de receptor de eventos en Visual Studio 2010
Recursos adicionales
Se aplica a: Microsoft SharePoint Foundation 2010
Proporcionado por: Ali Badereddin, Microsoft Corporation | Nick Gattuccio, Microsoft Corporation
Contenido
Conceptos básicos sobre eventos en SharePoint Foundation 2010
Trabajar con eventos en SharePoint Foundation 2010
Uso de la plantilla de receptor de eventos en Visual Studio 2010
Recursos adicionales
Conceptos básicos sobre eventos en SharePoint Foundation 2010
Un receptos de eventos en Microsoft SharePoint Foundation 2010 es simplemente un método al que se llama cuando se produce una acción desencadenante en un objeto especificado de SharePoint. Los eventos desencadenantes incluyen acciones como agregar, actualizar, eliminar, mover, proteger y desproteger. Los objetos de SharePoint que escuchan eventos (es decir, hosts de receptores de eventos) incluyen objetos como colecciones de sitios, sitios, listas y flujos de trabajo.
Los eventos son herramientas valiosas para programadores de SharePoint. Cuando un usuario realiza una acción que afecta a un sitio de SharePoint, se puede interceptar esa acción y responder a ella con código personalizado. Por ejemplo, si un jefe de proyecto necesita que se le avise cuando se agregan nuevos documentos o archivos a una biblioteca de documentos determinada, se puede escribir código de receptor de eventos para que se envíe una notificación por correo electrónico al jefe de proyecto y, a continuación, enlazar dicho código a la acción de adición de elementos en la biblioteca de documentos. SharePoint Foundation 2010 proporciona enorme flexibilidad para detectar y responder a eventos de SharePoint.
Nota
Microsoft Visual Studio 2010 ahora proporciona una plantilla de proyecto de receptor de eventos de SharePoint que realiza automáticamente muchas de las tareas que se describen en este artículo. Para proporcionar descripciones completas de las acciones que se producen en toda la canalización de eventos, no usamos la plantilla de proyecto de receptor de eventos de Visual Studio 2010. Sin embargo, ofrecemos un breve resumen del uso de Visual Studio 2010 para crear receptores de eventos y ofrecemos ejemplos que usan la plantilla.
Los eventos se introdujeron primero en Windows SharePoint Services 2.0, pero inicialmente solo se admitían en las bibliotecas de documentos. Los eventos de SharePoint se conocieron después como receptores de eventos. En Windows SharePoint Services 3.0, la infraestructura de eventos de SharePoint adquirió su forma actual, mediante los receptores de eventos administrados.
Los receptores de eventos mejoraron con respecto a los anteriores de varias formas. Son más fáciles de usar, tienen más tipos de eventos, y se admiten en listas, tipos de contenido, flujos de trabajo y sitios. En SharePoint Foundation 2010, se introdujeron los eventos web y las nuevas listas; además, las colecciones de sitios ahora pueden actuar como hosts de eventos, los eventos ahora pueden ser sincrónicos y se mejoró la suplantación y cancelación de eventos.
Funcionamiento de los eventos de SharePoint: todo lo que necesita saber en un solo párrafo
Un receptor de eventos de SharePoint está enlazado a un objeto de SharePoint (el host de eventos) y responde a una acción de usuario al activar el código de receptor de eventos. Compile el código de receptor de eventos en un ensamblado administrado, es decir, un archivo .dll que se implementa en la memoria caché global de ensamblados.
¿Dónde puedo usar receptores de eventos?
Si desea agregar comportamientos a las operaciones que se producen en SharePoint, puede usar receptores de eventos para desencadenar el código personalizado cada vez que una operación determinada tenga lugar. En la tabla 1 se enumeran las diversas operaciones en las que puede conectar el código personalizado.
Tabla 1. Operaciones disponibles para los receptores de eventos
Objeto |
Operaciones |
|---|---|
Colección de sitios |
|
Web |
|
Lista |
|
Campo |
|
Elemento |
|
Flujo de trabajo |
|
¿Qué son los receptores de eventos?
Un receptor de eventos es un fragmento de código administrado que responde a eventos de SharePoint cuando se producen acciones desencadenantes específicas en un objeto de SharePoint. Las acciones desencadenantes incluyen actividades como agregar, actualizar, eliminar, mover, proteger y desproteger.
Para crear un receptor de eventos, se hereda de una de las clases base del receptor de eventos. SharePoint proporciona cinco clases base de receptores de eventos. (Vea la tabla 2 en la sección siguiente). Tenga en cuenta que cada una de las clases base solo admite eventos y hosts de eventos especificados. Debe seleccionar la clase de base del receptor de eventos correcto para el tipo de host que desea admitir.
Después de escribir los receptores de eventos en la clase del receptor de eventos, debe compilar el receptor en un ensamblado administrado y, a continuación, colocarlo en la memoria caché global de ensamblados (GAC). Por último, deberá enlazar los receptores de eventos a un host de eventos adecuado. Más adelante en este artículo, se describirá el enlace de eventos y los distintos métodos con los que se pueden enlazar eventos.
¿Qué son los hosts de eventos?
Los hosts de eventos son objetos de SharePoint comunes que esperan recibir eventos; en otras palabras, objetos cuyos receptores de eventos "escuchan" eventos de SharePoint. Estos tipos de objetos de host de eventos de SharePoint incluyen instancias de objetos comunes como, por ejemplo, colecciones de sitios, sitios y listas de SharePoint. Cada tipo de host de eventos tiene un conjunto específico de tipos base de receptores de eventos desde el que puede heredar.
En la tabla 2 se enumeran las clases base del receptor de eventos así como los tipos de host de eventos compatibles con cada receptor, junto con los eventos compatibles.
Tabla 2. Clases base de receptores de eventos y eventos compatibles
Clase base del receptor de eventos |
Tipos de host de eventos disponibles |
Eventos compatibles |
|---|---|---|
|
|
|
SPListEventReceiver (listas) |
|
|
SPListEventReceiver (campos) |
|
|
|
|
|
|
|
|
|
|
Conceptos principales en el modelo de eventos de SharePoint
Además de las partes fundamentales del modelo de eventos (receptores de eventos, hosts de eventos y los propios eventos), a continuación se presentan los principales conceptos del panorama del modelo de eventos de SharePoint.
Eventos previos
Un evento previo se produce antes de que ocurra la operación actualmente solicitada. Por ejemplo, el evento ItemAdding es un evento previo que se genera antes de que se agregue un elemento a una lista de SharePoint.
Visto de otra forma, los eventos previos se generan cuando se produce una acción antes de que SharePoint escriba en la base de datos de contenido. Esto proporciona una oportunidad para que un receptor de eventos realice tareas antes de que los datos se confirmen en una base de datos. Un buen ejemplo del uso de eventos previos es la realización de validación de datos, ya que los eventos previos se desencadenan antes de que se confirmen los datos. También se pueden usar eventos previos (o sincrónicos) para cancelar acciones del usuario, por ejemplo, si se produce un error en la validación de datos.
El código de receptor de eventos desencadenado por un evento previo ejecuta el mismo subproceso que ejecuta la acción del usuario que lo desencadenó. Por este motivo, los eventos previos siempre son sincrónicos. Se pueden identificar los eventos previos porque sus nombres de miembro terminan con el sufijo "-ing": ItemAdding, ListAdding, etc.
Eventos posteriores
Un evento posterior se genera después de que ocurra la operación actualmente solicitada. Por ejemplo, el evento ItemAdded es un evento posterior que se genera después de que un elemento se agregue a una lista de SharePoint.
Los eventos posteriores desencadenan receptores de eventos que se ejecutan después de que las acciones del usuario se confirmen en la base de datos de contenido; invocan código que se ejecuta después de modificarse la base de datos. Esto permite ejecutar la lógica que se produce después de que un usuario haya completado una acción específica.
Los eventos posteriores se pueden ejecutar de manera sincrónica o asincrónica. Si el evento posterior es sincrónico, se ejecuta en el mismo subproceso en el que se produce la acción desencadenante. Sin embargo, si el evento posterior es asincrónico, se ejecuta en un subproceso independiente.
Se pueden identificar los eventos posteriores porque sus nombres de miembro terminan con el sufijo "-ed": ItemDeleted, WebProvisioned, etc.
Eventos sincrónicos
Un evento sincrónico se ejecuta en el mismo subproceso en el que se produce la acción desencadenante. Por ejemplo, cuando el usuario agrega un elemento desde la interfaz de usuario de SharePoint, el evento se ejecuta completamente antes de devolverse al usuario y mostrar que se ha agregado el elemento.
Todos los eventos previos son eventos sincrónicos.
Eventos asincrónicos
Un evento asincrónico se produce en un momento posterior a la acción que lo desencadenó y se ejecuta en un subproceso distinto de aquel en que se ejecuta la acción desencadenante. Por ejemplo, cuando un usuario agrega un elemento a una biblioteca de documentos mediante la interfaz de usuario de SharePoint, el evento comienza a ejecutarse antes de devolver el control al usuario. Sin embargo, no hay ninguna garantía de que el receptor de eventos termine de ejecutarse antes de que se muestre el usuario al que se ha agregado el elemento.
Enlace de eventos
El enlace de eventos (también conocido como registro de eventos) se puede realizar mediante el modelo de objetos de servidor o mediante XML de característica. Las siguientes secciones proporcionan información detallada sobre cómo enlazar eventos en SharePoint Foundation.
Cancelación de eventos
La cancelación de eventos permite cancelar una operación de receptor de eventos en un evento previo antes de la conclusión de la acción. Por ejemplo, podemos escribir código en el receptor de eventos ItemAdding que cancela la acción de agregar el elemento. Por lo tanto, cuando el usuario intenta agregar un elemento, se cancela la operación y el elemento no se agrega a la lista. Cuando se cancele la operación, asegúrese de mostrar al usuario un mensaje de error o proporcionar un mensaje de error personalizado mediante la redirección del usuario a una dirección URL específica.
Secuencia de receptor de eventos
La secuencia de receptor de eventos especifica el orden en que se ejecuta un receptor de eventos en los casos donde un evento desencadena varios receptores de eventos. Por ejemplo, si dispone de dos receptores de eventos ItemAdded enlazados a la misma lista (uno del ensamblado "1" y el otro del ensamblado "2"), el receptor de eventos que está enlazado con un número de secuencia inferior se ejecuta primero. Un ejemplo práctico es agregar un receptor de eventos a una lista del sistema que ya tenga enlazado un receptor de eventos del sistema. En ese caso, asigne al nuevo receptor de eventos un número de secuencia más alto.
La canalización de eventos de SharePoint
La figura 1 ilustra cómo se producen los eventos de SharePoint con respecto a la sincronización y la secuenciación.
Figura 1. Canalización de eventos de SharePoint
.gif "Canalización de eventos de SharePoint")
Tenga en cuenta los siguientes detalles:
Los receptores de eventos sincrónicos se llaman en orden secuencial en función del número de secuencia especificado durante el enlace de eventos. Esto se aplica tanto a los eventos sincrónicos previos como a los posteriores.
Los subprocesos de receptores de eventos posteriores asincrónicos se inician en orden secuencial en función del número de secuencia. Sin embargo, no hay ninguna garantía de que finalicen en ese mismo orden.
Un evento posterior asincrónico puede iniciarse en cualquier momento después de que se realice su acción de usuario asociada. Puede iniciarse antes, al mismo tiempo o después de que se complete la solicitud web.
Después de que un usuario inicie una acción en la interfaz de usuario de SharePoint y antes de que SharePoint Foundation ejecute la acción del usuario, se generan los eventos previos sincrónicos. Si hay varios eventos previos sincrónicos, estos se generan en el orden especificado por su número de secuencia. De forma similar, los eventos posteriores sincrónicos se generan después de que SharePoint Foundation ejecute la acción del usuario. De igual forma, estos se generan en el orden especificado por el número de secuencia. Como puede ver, todos los eventos sincrónicos se procesan en el mismo subproceso en el que se produce la acción del usuario.
Sin embargo, los eventos posteriores asincrónicos se procesan en subprocesos secundarios.
Trabajar con eventos en SharePoint Foundation 2010
Básicamente, la creación de un evento de SharePoint consta de dos pasos. En primer lugar, se identifica la operación que se va a asociar a un evento, se hereda de la clase base del receptor de eventos apropiado y se escribe el código personalizado para el receptor de eventos. En segundo lugar, se enlaza el evento a un host de eventos de SharePoint apropiado. (Este paso también se conoce como "registrar" el evento).
Después de escribir el código de receptor de eventos y compilarlo en un ensamblado con firma segura, se puede usar cualquiera de estas dos maneras para enlazar el evento a su host de eventos: usar las API en el modelo de objetos de SharePoint o usar el XML de característica en una solución de SharePoint. Se describirán ambos métodos detalladamente.
Uso del modelo de objetos frente al uso de soluciones
En pocas palabras, la diferencia entre usar el modelo de objetos y usar soluciones para enlazar eventos de SharePoint es la siguiente: la técnica del modelo de objetos es más flexible y fácil de desarrollar, pero es difícil de implementar y mantener. Mientras que la técnica de las soluciones es menos flexible y más difícil de desarrollar, pero es mucho más fácil de implementar y mantener.
Al usar la técnica del modelo de objetos, tendrá todo el modelo de objetos de SharePoint a su disposición. Puede escribir el código del receptor de eventos, compilarlo en un ensamblado que se implemente en la GAC y ejecutar código para enlazar los eventos en el ensamblado a un host de eventos de SharePoint.
Esta técnica resulta útil cuando se encuentra en modo de desarrollo, ya que es fácil probar y realizar cambios en el código del receptor de eventos y el enlace de eventos y, a continuación, volver a generar e implementar el proyecto. Sin embargo, al mover el código de una plataforma de desarrollo a un entorno de producción, esta simplicidad se evapora porque debe implementarse todo de forma manual. Esto significa que debe copiar el código del receptor de eventos (es decir, el ensamblado administrado) a cada servidor front-end web individual del entorno de producción. A continuación, debe ejecutar el archivo ejecutable en uno de los servidores front-end web y ejecutar iisreset en cada uno de los servidores front-end web para actualizar la memoria caché en el proceso de trabajo de IIS (w3wp.exe). En un entorno de producción de gran tamaño, puede resultar una tarea muy compleja (y arriesgada).
La técnica de la solución de SharePoint se diferencia en el modo en que enlaza la definición del receptor de eventos. Además, al tener el código del receptor de eventos en el paquete de implementación (.wsp) junto con los archivos de solución, la implementación en un conjunto o granja de servidores es mucho más fácil y más confiable, y la definición del receptor de eventos está disponible con tan solo activar una característica. Otra ventaja importante de esta técnica es que los receptores de eventos se pueden implementar en código de confianza parcial (es decir, en soluciones de espacio aislado). A continuación, los administradores en el nivel de la colección de sitios pueden agregar receptores de eventos. (Antes de SharePoint 2010, solo los administradores de la granja de servidores podían agregar receptores de eventos).
A continuación, la implementación no precisa más pasos de los que normalmente se usan para la implementación de soluciones de SharePoint mediante un archivo .wsp. La ejecución de un comando único de implementación implementa el ensamblado del receptor y los enlaces de eventos en todos los servidores front-end web después de que se active la característica.
Visual Studio 2010 facilita aún más este proceso. El uso de Visual Studio proporciona la flexibilidad de la técnica del modelo de objetos y conserva la economía de la técnica de las soluciones. Como trabajaremos con receptores de eventos en las secciones siguientes, destacaremos las maneras en que Visual Studio 2010 ha simplificado enormemente el proceso.
Uso del modelo de objetos de servidor
Cuando se usa el modelo de objetos de servidor, las principales acciones que pueden preocupar son tres: la creación de código de evento, el enlace de eventos y la modificación o cambio de código de evento. En las siguientes secciones se describe cada paso detalladamente.
Nota
Aunque se usa Visual Studio en los siguientes ejemplos, no se usan las plantillas de proyecto de SharePoint que se incluyen con Visual Studio 2010. Por este motivo, se puede usar tanto Visual Studio 2008 como Visual Studio 2010 cuando se intente recrear los ejemplos siguientes.
Creación de eventos con el modelo de objetos
El primer paso para crear el receptor de eventos personalizado consiste en invalidar una de las clases base del receptor de eventos. Las cinco clases base del receptor de eventos de SharePoint se enumeran en la tabla 2 de este artículo, pero todas ellas heredan de la clase base del receptor de eventos principal, SPEventReceiverBase.
Para crear un receptor de eventos
En Visual Studio 2008 o Visual Studio 2010, cree un proyecto de biblioteca de clases de C# denominado, por ejemplo, MyReceiverAssembly.
.gif "Nota importante")
ImportanteSi usa Visual Studio 2010, asegúrese de seleccionar Microsoft .NET Framework 3.5 como destino. La razón es que SharePoint 2010 se basa en .NET Framework 3.5. Puede encontrar esta opción en la ficha Aplicación de las propiedades del proyecto, tal como se muestra en la figura 2.
Figura 2. Selección de .NET Framework 3.5 como destino
.gif "Selección de .NET Framework 3.5 como destino")
En la ficha Generar de las propiedades del proyecto, establezca Destino de la plataforma en x64 o Any CPU, tal como se muestra en la figura 3. No seleccione x86.
Figura 3. Selección de la plataforma de destino adecuada
.gif "Selección de la plataforma de destino adecuada")
En la ficha Firma de las propiedades del proyecto, seleccione Firmar el ensamblado.
Haga clic en Elija un archivo de clave de nombre seguro y, a continuación, elija Nueva.
En el cuadro de diálogo Crear clave de nombre seguro, en el cuadro de texto Nombre del archivo de clave, escriba cualquier nombre. Desactive la casilla de verificación Proteger mi archivo de clave mediante contraseña y, a continuación, haga clic en Aceptar.
Cambie el nombre de la clase; por ejemplo, MyReceiverClass.
Agregue una referencia a Microsoft.SharePoint.dll.
En la clase, cree una referencia al espacio de nombres Microsoft.SharePoint insertando la siguiente instrucción:
using Microsoft.SharePoint;
Herede de la subclase apropiada de SPEventReceiverBase, según el evento que desee crear (vea la tabla 2). Por ejemplo, si desea crear y enlazar un evento ItemAdded, herede de la clase base SPItemEventReceiver, tal como se indica a continuación:
Public class MyReceiverClass : SPItemEventReceiver
Defina los métodos para los eventos que desea implementar. Una técnica útil consiste en escribir public override y, a continuación, presionar la barra espaciadora. En Visual Studio, IntelliSense muestra los eventos disponibles en la clase, tal como se muestra en la figura 4.
Figura 4. Uso de IntelliSense para ver eventos disponibles
.gif "Uso de IntelliSense para ver eventos disponibles")
Si seleccionó el evento ItemAdded, ahora tiene la siguiente definición de método:
Public override void ItemAdded(SPItemEventProperties properties) { base.ItemAdded(Properties; }Compile la biblioteca de clases en un archivo DLL.
Para colocar el archivo DLL en la GAC, navegue a la carpeta %WINDIR%\assembly y, a continuación, arrastre el ensamblado en la carpeta.
Si recibe un error "acceso denegado" u otro problema que impida colocar el ensamblado en la memoria caché, puede usar el procedimiento siguiente.
Asegúrese de que Herramientas de desarrollo de SharePoint en Visual Studio 2010 está instalado en su equipo.
Inicie el símbolo del sistema de Visual Studio.
Escriba gacutil /i seguido de la ruta de acceso al ensamblado. Si la operación se realiza correctamente, recibirá el mensaje "Ensamblado agregado correctamente a la caché".
Para confirmar que se agregó el ensamblado, escriba el siguiente comando en el símbolo del sistema para obtener una lista de todos los ensamblados que se encuentran en el directorio especificado en la memoria caché de ensamblados (en este caso, en el directorio de la memoria caché denominado MyReceiverAssembly):
gacutil /l MyReceiverAssembly
Enlace de eventos con el modelo de objetos
Al usar el modelo de objetos de SharePoint Foundation, puede enlazar (registrar) cualquier objeto que tenga la propiedad EventReceivers. La propiedad EventReceivers es de tipo SPEventReceiverDefinitionCollection, que facilita la adición de definiciones de receptor de eventos a los hosts de eventos. La siguiente es una lista de objetos de SharePoint que tienen esta propiedad y pueden servir como hosts de eventos.
SPSite (SPSite.EventReceivers)
SPWeb (SPWeb.EventReceivers)
SPList (SPList.EventReceivers)
SPContentType (SPContentType.EventReceivers)
SPFile (SPFile.EventReceivers)
SPWorkflow (SPWorkflowEventReceivers())
Para enlazar un receptor de eventos
En Visual Studio 2008 o Visual Studio 2010, cree un proyecto de aplicación de consola de C# denominado, por ejemplo, RegisterEvents.
ImportanteSi usa Visual Studio 2010, asegúrese de seleccionar Microsoft .NET Framework 3.5 como destino. La razón es que SharePoint 2010 se basa en .NET Framework 3.5. Puede encontrar esta opción en la ficha Aplicación de las propiedades del proyecto, tal como se muestra en la figura 2.
Agregue una referencia a Microsoft.SharePoint.dll.
En la clase, cree una referencia al espacio de nombres Microsoft.SharePoint insertando la siguiente instrucción:
using Microsoft.SharePoint;
Agregue un nuevo elemento de tipo SPEventReceiverDefinition a la colección EventReceivers en el objeto especificado, similar al siguiente:
SPEventReceiverDefinition def = list.EventReceivers.Add();
Para obtener el nombre completo del ensamblado que creó en el procedimiento anterior, vaya a la GAC, busque el ensamblado, haga clic con el botón secundario en la entrada del ensamblado y haga clic en Propiedades. La ventana de propiedades debe ser similar a la de la figura 5.
Figura 5. Propiedades de ensamblado en la GAC
.gif "Propiedades de ensamblado en GAC")
Copie los valores de la ventana de propiedades para especificar el nombre completo, la versión, la referencia cultural y el token de clave pública. En este ejemplo, el código fuente aparece como se muestra a continuación:
def.Assembly = "MyReceiverAssembly, Version=1.0.0.0, Culture=Neutral,PublicKeyToken=12e5e5525fb3d28a";
Establezca la propiedad Class. La propiedad Class representa el nombre de clase completo de la clase que contiene el receptor de eventos, en el formulario namespace.class. En este ejemplo, el código fuente aparece como se muestra a continuación:
def.Class = "MyReceiverAssembly.MyReceiverClass";
Establezca la propiedad Type. En este ejemplo, el código fuente aparece como se muestra a continuación:
def.Type = SPEventReceiverType.ItemAdded;
Establezca la propiedad Name. Esta propiedad es opcional. Puede proporcionar un nombre para la definición del receptor de eventos o puede omitir el valor. En este ejemplo, el código fuente aparece como se muestra a continuación:
def.Name = "My ItemAdded Event Receiver";
Establezca la propiedad Synchronization. Esta propiedad es opcional. Si no especifica un valor para esta propiedad, la propiedad se establece en Default (es decir, SPEventReceiverSynchronization.Default). El comportamiento predeterminado es para eventos previos que van a ser sincrónicos y eventos posteriores que van a ser asincrónicos. En este ejemplo, el código fuente aparece como se muestra a continuación:
def.Synchronization = SPEventReceiverSynchronization.Synchronous;
Establezca la propiedad SequenceNumber. Esta propiedad es opcional. Use esta propiedad para establecer el orden en que se desencadenan los eventos cuando varios eventos se encuentran en la definición del receptor de eventos. Si no establece este valor, su valor predeterminado es 10 000. Al establecer este valor, puede seleccionar cualquier valor entre 0 y (216)-1.
Para guardar la definición del receptor de eventos en la base de datos de contenido de SharePoint, agregue la siguiente instrucción:
def.Update();
A continuación, se muestra el código fuente completo para el procedimiento anterior. Al ejecutar este código, el evento se registra en la lista de tareas del sitio https://localhost. Al crear un nuevo elemento en la lista, el evento ItemAdded se desencadena.
using (SPSite site = new SPSite("https://localhost"))
{
using (SPWeb web = site.OpenWeb())
{
SPList list = web.Lists["Tasks"];
SPEventReceiverDefinition def = list.EventReceivers.Add();
def.Assembly =
"MyReceiverAssembly, Version=1.0.0.0, Culture=Neutral, PublicKeyToken=12e5e5525fb3d28a";
def.Class = "MyReceiverAssembly.MyReceiverClass";
def.Type = SPEventReceiverType.ItemAdded;
def.Name = "My ItemAdded Event Receiver";
def.Synchronization = SPEventReceiverSynchronization.Synchronous;
def.SequenceNumber = 1000;
def.Update();
}
}
Cambio de eventos
El modelo de eventos de SharePoint hace que sea más fácil cambiar y volver a implementar el código del receptor de eventos. Las siguientes instrucciones ilustran cómo realizar cambios en el proyecto de ejemplo MyReceiverAssembly.
Para actualizar un receptor de eventos
En Visual Studio, abra el proyecto (por ejemplo, el proyecto MyReceiverAssembly) y realice los cambios.
Recompile el proyecto para crear una nueva compilación del archivo DLL.
Coloque la nueva compilación del archivo DLL en la GAC. Asegúrese de sobrescribir o eliminar el archivo DLL anterior.
Ejecute iisreset para borrar la memoria caché de IIS y, por tanto, cargar la nueva versión del ensamblado en la GAC. Esta acción garantiza que SharePoint recoja los cambios.
Uso de soluciones de SharePoint
En lugar de usar el modelo de objetos de SharePoint para crear e implementar los receptores de eventos, puede usar las soluciones de SharePoint. En esta sección, vamos a recorrer el proceso manual de creación de una solución de receptor de eventos.
Se crean eventos para la implementación al usar soluciones de SharePoint en la misma forma que cuando se usa el modelo de objetos de SharePoint. Siga el procedimiento descrito en la sección Creación de eventos con el modelo de objetos para crear los eventos.
La diferencia real entre estas dos maneras de implementar eventos está en el enlace, para el que se usa una característica de SharePoint implementada en un archivo de solución (.wsp).
Enlace de eventos mediante el uso de soluciones
En el siguiente procedimiento se crea una característica de SharePoint que toma el evento de ejemplo (el evento ItemAdded, que se creó en el archivo DLL MyReceiverAssembly) y lo enlaza a la lista Tareas en el sitio web en el que se desea activar la característica.
Para crear una característica de SharePoint
Cree una carpeta con el mismo nombre que la característica.
En la nueva carpeta, cree dos archivos XML, denominados feature.xml y eventbinder.xml.
Para habilitar IntelliSense en los archivos XML, acceda a las propiedades de archivo y agregue una referencia al archivo de esquema de destino (.xsd), que se encuentra en el directorio …/TEMPLATE/XML/wss.xsd.
Normalmente, debe volver a crear este vínculo cada vez que abra el archivo XML. Sin embargo, si está trabajando en un proyecto de Visual Studio, todo lo que necesita hacer es agregar el archivo de esquema al proyecto.
Pero si crea muchos archivos CAML en varios proyectos de Visual Studio, y si lo hace con mucha frecuencia, este proceso puede ser engorroso. Un método alternativo consiste simplemente en cargar el archivo XSD cada vez que se abra un archivo XML que haga referencia al esquema. Para ello, haga lo siguiente.
Busque el archivo XML denominado Catalog.xml en la carpeta de instalación de Visual Studio, que suele ser C:\Program Files\Microsoft Visual Studio 9.0\Xml\Schemas.
Para hacer referencia al archivo de esquema wss.xsd desde el archivo Catalog.xml, agregue la siguiente etiqueta. Asegúrese de que el valor href señale a la ubicación correcta del archivo wss.xsd.
<Schema href="C:/Program Files/Common Files/Microsoft Shared/Web Server Extensions/12/TEMPLATE/XML/wss.xsd" targetNamespace="https://schemas.microsoft.com/sharepoint/" />
.gif "Sugerencia")
SugerenciaSi usa Visual Studio 2010, puede omitir el paso 3. Al abrir un archivo XML que contiene el atributo xmlns="https://schemas.microsoft.com/sharepoint/", Visual Studio 2010 agrega automáticamente una referencia a wss.xsd y habilita IntelliSense.
En el archivo feature.xml, cree un elemento <Feature>. Establezca el atributo xmlns en "https://schemas.microsoft.com/sharepoint/", establezca el atributo Id en un identificador único global (GUID), establezca el atributo Scope en "Web" y establezca el atributo Title en "EventBinderFeature".
ImportantePara el atributo Id, debe proporcionar un GUID válido, que puede obtener en Visual Studio si ejecuta guidgen.exe.
En el elemento <Feature>, agregue un elemento <ElementManifests>.
En el elemento <ElementManifests>, agregue un elemento <ElementManifest>. Establezca el atributo Location en "eventbinder.xml".
En el archivo eventbinder.xml, cree un elemento <Elements>. Establezca el atributo xmlns en "https://schemas.microsoft.com/sharepoint/".
En el elemento <Elements>, agregue un elemento <Receivers>. Establezca el atributo ListUrl en "Tasks".
En el elemento <Receivers>, agregue un elemento <Receiver>.
En el elemento <Receiver>, agregue los siguientes elementos, con un valor apropiado para cada uno:
<Assembly>
<Class>
<Type>
<Name>
<Synchronization>
<SequenceNumber>
Después de completar el procedimiento anterior, el archivo feature.xml debería parecerse al siguiente.
<Feature Id="E54C7FF5-1DF3-4B0B-8FFF-DB3185ECE8A6"
Scope="Web"
Title="Event Binder Feature"
xmlns="https://schemas.microsoft.com/sharepoint/">
<ElementManifests>
<ElementManifest Location="eventbinder.xml" />
</ElementManifests>
</Feature>
Y el archivo eventbinder.xml debe ser similar al siguiente.
<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
<Receivers ListUrl="Lists/Tasks">
<Receiver>
<Assembly>MyReceiverAssembly, Version=1.0.0.0, Culture=Neutral,
PublicKeyToken=12e5e5525fb3d28a</Assembly>
<Class>MyReceiverAssembly.MyReceiverClass</Class>
<Type>ItemAdded</Type>
<Name>My ItemAdded Event Receiver</Name>
<Synchronization>Synchronous</Synchronization>
<SequenceNumber>1000</SequenceNumber>
</Receiver>
</Receivers>
</Elements>
Empaquetado de la solución
Para implementar receptores de eventos en la instalación de SharePoint, debe ensamblar los archivos en un archivo de paquete de solución (.wsp). El archivo .wsp es simplemente un archivo .CAB cuya extensión de nombre de archivo es .wsp.
El archivo de manifiesto de la solución indica a SharePoint qué hacer con los archivos que están empaquetados en el archivo .wsp. Por ejemplo, el elemento <FeatureManifest> especifica que esta carpeta es una característica de SharePoint y, por tanto, debe implementarse en %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\FEATURES e instalarse en la granja de servidores. Asimismo, el elemento <Assembly> especifica que este archivo es un ensamblado; su atributo DeploymentTarget indica si se va a implementar el ensamblado en la GAC o en una carpeta bin de la aplicación web.
Prepare, cree y edite el archivo manifest.xml del modo siguiente:
Para preparar el contenido de la solución
Cree una carpeta denominada "EventSolution".
Copie la carpeta de la característica EventBinder en la carpeta EventSolution.
Copie el ensamblado MyReceiverAssembly.dll en la carpeta EventSolution.
Cree un archivo XML denominado "manifest.xml" en la carpeta EventSolution.
Para modificar el archivo manifest.xml
En el archivo manifest.xml, cree un elemento <Solution>. Establezca el atributo xmlns en "https://schemas.microsoft.com/sharepoint/", establezca el atributo SolutionId en un GUID y establezca el atributo Title en "Event Receiver Solution".
En el elemento <Solution>, agregue un elemento <FeatureManifests>.
En el elemento <FeatureManifests>, agregue un elemento <FeatureManifest>. Establezca el atributo Location en "EventBinder\feature.xml".
En el elemento <Solution>, agregue un elemento <Assemblies>.
En el elemento <Assemblies>, agregue un elemento <Assembly>. Establezca el atributo Location en "MyReceiverAssembly" y establezca el atributo DeploymentTarget en "GlobalAssemblyCache".
El archivo manifest.xml ahora debería parecerse a lo siguiente.
<Solution SolutionId="11C76135-CEEC-475B-9A93-67E5EF151B3C"
Title="Event Receiver Solution"
xmlns="https://schemas.microsoft.com/sharepoint/">
<FeatureManifests>
<FeatureManifest Location="EventBinder\feature.xml"/>
</FeatureManifests>
<Assemblies>
<Assembly Location="MyReceiverAssembly"
DeploymentTarget="GlobalAssemblyCache">
</Assembly>
</Assemblies>
</Solution>
Ahora que el contenido de la solución está listo, lo único que queda es crear el archivo de directivas Diamond (DDF). Un archivo DDF contiene información que Microsoft Cabinet Maker (makecab.exe) usa para identificar cómo empaquetar y comprimir los archivos en un archivo .CAB. (El propio archivo DDF no se coloca en el archivo .CAB).
Para crear un archivo DDF
En la carpeta EventSolution, cree un archivo denominado "cab.ddf".
Abra el archivo cab.dff en un editor de texto, como el Bloc de notas y agregue la siguiente información.
; .OPTION EXPLICIT .Set CabinetNameTemplate=MyEventSolution.wsp .set DiskDirectoryTemplate=CDROM .Set CompressionType=MSZIP .Set UniqueFiles="ON" .Set Cabinet=on .Set DiskDirectory1=Package manifest.xml manifest.xml MyReceiverAssembly.dll MyReceiverAssembly.dll EventBinder\feature.xml EventBinder\feature.xml EventBinder\EventBinder.xml EventBinder\EventBinder.xmlGuarde el archivo.
| Importante |
|---|
En un archivo DDF, asegúrese de que la primera línea comienza con un punto y coma. |
La directiva OPTION EXPLICIT fuerza la declaración explícita de todas las variables en el archivo. Al establecer UniqueFiles en "ON" se garantiza que los archivos de destino sean únicos. "ON" es el valor predeterminado, porque usar el mismo nombre de archivo dos veces normalmente significa que el mismo archivo se incluyó accidentalmente dos veces, lo que desperdicia espacio en disco.
Las últimas cuatro líneas en este archivo DDF son las asignaciones de archivo: el primer nombre de cada línea es el origen; el segundo nombre es el destino.
Para crear el archivo de paquete de solución, abra un símbolo del sistema, navegue a la carpeta EventSolution y escriba el siguiente comando:
makecab /F cab.ddf
Cabinet Maker crea el archivo .wsp en una subcarpeta de la carpeta EventSolution denominada "Package". El nombre del nuevo archivo es MyEventSolution.wsp.
Implementación de la solución
SharePoint 2010 proporciona dos tipos de soluciones: soluciones de granja de servidores y soluciones de espacio aislado. Las soluciones de espacio aislado son importantes porque permiten que el administrador de una colección de sitios cargue y active soluciones en el ámbito de la colección de sitios. Con las soluciones de espacio aislado, deja de ser necesario tener acceso al equipo de los archivos WFE.
Por definición, sin embargo, el uso de soluciones de espacio aislado limita el código que se puede ejecutar. Por ejemplo, si el código en nuestro receptor de eventos intenta tener acceso al disco, el código se ejecuta sin problemas cuando la solución se implementa como una solución de granja de servidores. Pero si el receptor de eventos se implementa como una solución de espacio aislado, se produce una excepción de tiempo de ejecución cuando se intenta tener acceso al disco.
Nota
En SharePoint 2010, Windows PowerShell reemplaza a la herramienta de administración de Stsadm.exe. Todavía puede usar Stsadm para implementar soluciones de granja de servidores, pero se recomienda usar Windows PowerShell. No se puede usar Stsadm para implementar soluciones de espacio aislado.
Para implementar una solución de granja de servidores
Cargue la solución al almacén de soluciones de granja de servidores mediante la ejecución del siguiente comando de Windows PowerShell:
Add-SPSolution -LiteralPath full_path_to_solution
Para activar la solución, ejecute el comando siguiente:
Install-SPSolution solution_name.wsp -GACDeployment
Para implementar una solución de espacio aislado
Cargue la solución a la galería de soluciones de colecciones de sitios mediante la ejecución del siguiente comando de Windows PowerShell:
Add-SPUserSolution -LiteralPath full_path_to_solution -Site siteUrl
Para activar la solución, ejecute el comando siguiente:
Install-SPUserSolution solution_name.wsp -Site siteUrl
Cuando se implementa la solución, las características se copian a la carpeta TEMPLATE\FEATURES, los ensamblados administrados se colocan en la GAC y otros archivos se colocan en sus respectivas carpetas en TEMPLATES. Ahora puede activar las características.
Si necesita retirar una solución, use uno de los siguientes comandos de Windows PowerShell:
Solución de granja de servidores: Uninstall-SPSolution solution_name.wsp
Solución de espacio aislado: Uninstall-SPUserSolution solution_name.wsp -Site siteUrl
Después de retirar una solución, puede eliminarla con uno de los siguientes comandos:
Solución de granja de servidores: Remove-SPSolution solution_name.wsp
Solución de espacio aislado: Remove-SPUserSolution solution_name.wsp -Site siteUrl
Uso de la plantilla de receptor de eventos en Visual Studio 2010
Visual Studio 2010 proporciona un conjunto ampliado de plantillas de proyecto de SharePoint tanto en Microsoft Visual Basic como en C#, incluida una plantilla para los receptores de eventos de SharePoint. La plantilla de proyecto simplifica el control de eventos para objetos de SharePoint como, por ejemplo, sitios, listas, flujos de trabajo y otros elementos comunes.
Nota
Este artículo no se centra en la plantilla de proyecto de Visual Studio para los receptores de eventos ya que pretende proporcionar todos los detalles técnicos que se producen en el modelo de eventos de SharePoint, incluso aquellos que están ocultos por la plantilla de proyecto de Visual Studio. No obstante, esta sección muestra lo fácil que es crear un receptor de eventos básico con esta plantilla de proyecto.
Al crear un proyecto de receptor de eventos mediante la plantilla de proyecto del receptor de eventos en Visual Studio, varios de los pasos descritos en este artículo se completan automáticamente. Estos pasos incluyen crear y firmar el ensamblado, crear la característica para enlace de eventos, empaquetar, implementar y depurar la solución.
Para crear un receptor de eventos de SharePoint mediante la plantilla de proyecto del receptor de eventos de Visual Studio
En Visual Studio 2010, cree un nuevo proyecto mediante la plantilla de receptor de eventos de SharePoint 2010.
Seleccione el nivel de confianza para la solución de SharePoint en función de la implementación del código de receptor de eventos. Si la solución no tiene necesidad de acceso de nivel de sistema, la solución de espacio aislado es la alternativa preferida, ya que su uso resulta más fácil y más probable.
Seleccione los eventos que desee invalidar. En este caso, deseamos invalidar el evento ItemAdded y enlazarlo a la lista de tareas.
¿Qué tipo de receptores de eventos desea? Eventos de elemento de lista
¿Qué elemento debería ser el origen del evento? Tareas
Controlar los eventos siguientes: se agregó un elemento
Haga clic en Finalizar.
En el evento ItemAdded, agregue el código personalizado.
En la barra de menús, haga clic en Generar y, a continuación, elija Implementar solución.
Ya se ha empaquetado, agregado e implementado la solución. Incluso puede establecer un punto de interrupción en el código de receptor de eventos y depurarlo.
Para explorar varios ejemplos prácticos del uso del modelo de eventos de SharePoint, lea la segunda parte de este artículo: Uso de receptores de eventos en SharePoint Foundation 2010 (parte 2 de 2).
Recursos adicionales
Para obtener más información, vea los siguientes recursos: