Criando e Explorando os Event Receivers no MOSS 2007 \ WSS 3.0

Nesse artigo gostaria de falar um pouco sobre Event Handlers no MOSS 2007 / WSS 3.0, na minha opinião um dos recursos de extensibilidade mais fantástico do SharePoint!

por Wagner Amorim

Overview

Hoje gostaria de falar um pouco sobre Event Handlers no MOSS 2007 / WSS 3.0, na minha opinião um dos recursos de extensibilidade mais fantástico do SharePoint!

Event Receiver, como é chamado no SharePoint, tem o objetivo de manipular eventos que ocorrem nas aplicações Sharepoint, abaixo listo os Tipos de Eventos suportados:

· Microsoft.SharePoint.SPWebEventReceiver - Nível Site

SiteDeleted

SiteDeleting

WebDeleted

WebDeleting

WebMoved

WebMoving

· Microsoft.SharePoint.SPListEventReceiver - Nível Lista

FieldAdded

FieldAdding

FieldDeleted

FieldDeleting

FieldUpdated

FieldUpdating

· Microsoft.SharePoint.SPItemEventReceiver - Nível Item de Lista

ItemAdded

ItemAdding

ItemAttachmentAdded

ItemAttachmentAdding

ItemAttachmentDeleted

ItemAttachmentDeleting

ItemCheckedIn

ItemCheckedOut

ItemCheckingIn

ItemCheckingOut

ItemDeleted

ItemDeleting

ItemFileConverted

ItemFileMoved

ItemFileMoving

ItemUncheckedOut

ItemUncheckingOut

ItemUpdated

ItemUpdating

Dentro desses tipos vocês podem notar que existem os eventos síncronos e assíncronos, vejamos algumas características deles:

Eventos Síncronos (terminam com “ing” no final)

§ Antes do Evento acontecer (ex: Item sendo excluído).

§ Bloqueia o evento até que o código seja executado.

§ Permite que o evento seja cancelado, antes que ele seja concluído, antes que os eventos assíncronos aconteçam.

Eventos Assíncronos (terminam com “end” no final)

§ Ocorre quando o evento já aconteceu (ex: Item de lista criado).

§ Não intercepta a execução do evento durante o código.

Solução

Bom... Após um breve overview, vamos a prática, vou utilizar um caso simples que utilizei Event Receivers esses dias, precisava preencher um campo X que era a união de dois outros campos de uma lista customizada.

Vamos utilizar o método “ItemAdded” para interceptar os itens quando eles forem criados, nosso EventReceiver vai se encarregar de preencher o “campo X” nesse momento ;).

Para esse exemplo, vou utilizar um ambiente com o Visual Studio 2008, Windows SharePoint Services 3.0 e o Windows Server 2003 instalados em uma VM.

Nossa lista do tipo “Custom List” (ex: ListaX) irá conter basicamente os seguintes campos:

§ Title – texto de uma linha - obrigatório

§ MeuID - texto de uma linha

§ Created – data – obrigatório

Obs.: Os campos “Created” e “Title” são criados automaticamente pelo SharePoint.

Siga os passos abaixo:

1 - Abra o Visual Studio.

2 – Crie um Novo Projeto do tipo “Class Library”.

3 – Adicione referência a assembly Microsoft.SharePoint no seu projeto.

4 – Renomeie a classe que é adicionada por padrão (ex: ManipulandoItens).

5 – Importe para essa classe o namespace Microsoft.SharePoint.

using Microsoft.SharePoint;

6 – No nosso caso vamos herdar a classe SPItemEventReceiver, porque queremos manipular eventos no nível de itens de lista.

public class ManipulandoItens:SPItemEventReceiver

7 – Implemente “override” no método ItemAdded e a lógica com o código para preencher o nosso campo, nesse caso a coluna “MeuID”

public override void ItemAdded(SPItemEventProperties properties)

{

SPListItem Item = properties.ListItem;

string Titulo = Item["Title"].ToString();

string DataCriacao = Convert.ToDateTime(Item["Created"]).ToShortDateString();

Item["MeuID"] = Titulo + "_" + DataCriacao;

Item.SystemUpdate();

}

Verifiquem que eu utilizei o método “SystemUpdate()”, invez de utilizar “Update”, como é mais comum, para quem não sabe esse método é utilizado na prática para não registrar a alteração do item, evitar por exemplo novas versões do documento, ou seja, a alteração nessa versão é transparente para a aplicação, como uma alteração realizada pelo “sistema”.

Nosso método que manipula o evento ItemAdded está criado, toda vez que um item for adicionado o SharePoint irá executar esse código.

Desta forma temos um exemplo de manipulação de eventos assíncronos, também irei criar um exemplo para eventos síncronos, vamos simplesmente interceptar todo evento de exclusão de itens.

8 – Implemente “override” no método de “ItemDeleting” e a lógica com o código para simular um erro ao excluir um item.

public override void ItemDeleting(SPItemEventProperties properties)

{

properties.Cancel = true;

properties.ErrorMessage = "Os itens da lista " + properties.ListTitle + " não podem ser excluídos.";
}

9 – Compile a aplicação e elimine qualquer erro que aparecer (CTRL+SHIFT+B).

10 – Associe uma “strongly name” à sua assembly.

§ Na Janela “Solution Explorer” do VS 2008, clique 2 vezes na pasta “Properties” do seu projeto.

§ Na janela Properties, navegue até a guia “Signing”.

§ Marque a opção “Sign the assembly”.

§ No dropdown “Choose a strong name key file”, clique em New e atribua um nome para o “Key file name”, desmarque a opção “Protect my key file with a password”.

§ Clique em OK e depois em Salvar na janela Properties.

11 – Compile novamete a aplicação (CTRL+SHIFT+B).

Agora precisamos fazer o deploy do nosso Event Receiver no SharePoint, existem várias formas de executar esse procedimento, vou optar pelo conceito simples de features, seguindo o exemplo do SDK do WSS 3.0.

12 – Faça o Deploy da DLL para o SharePoint.

§ Copie a DLL (bin\Debug) gerada pelo seu projeto no GAC (C:\WINDOWS\assembly).

Com a feature conseguiremos informar em qual tipo de listas o SharePoint vai ativar o Event Receiver.

13 - Criando uma Feature.

Recomendo que por organização e facilidade, adicionem os próximos arquivos necessários para a Feature no projeto do Visual Studio, seguindo esse modelo abaixo:

§ Adicione um novo item ao projeto chamado Feature.xml, do template “XML File”.

§ Adicione o seguinte código ao arquivo:

<Feature Scope="Web"

Title="Nossos Event Handlers"

Id="D6A0CD1F-F1B4-4E94-BD09-97F79A6EE60E"

xmlns="http://schemas.microsoft.com/sharepoint/">

<ElementManifests>

<ElementManifest Location="Elements.xml"/>

</ElementManifests>

</Feature>

§ Altere a propriedade “ID”, para um novo GUID, existem vários programas que geram um novo GUID, existe até sites que geram on-line (ex: http://createguid.com).

§ Adicione um novo item ao projeto chamado Elements.xml, do template “XML File”.

§ Adicione o seguinte código ao arquivo:

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">

<Receivers ListTemplateId="100">

<Receiver>

<Name>Item Adicionado</Name>

<Type>ItemAdded</Type>

<SequenceNumber>10001</SequenceNumber>

<Assembly>MeuEventReceiver, Version=1.0.0.0, Culture=neutral, PublicKeyToken=27022ff382474ca0</Assembly>

<Class>MeuEventReceiver.ManipulandoItens</Class>

<Data></Data>

<Filter></Filter>

</Receiver>

<Receiver>

<Name>Item Excluindo</Name>

<Type>ItemDeleting</Type>

<SequenceNumber>10002</SequenceNumber>

<Assembly>MeuEventReceiver, Version=1.0.0.0, Culture=neutral, PublicKeyToken=27022ff382474ca0</Assembly>

<Class>MeuEventReceiver.ManipulandoItens</Class>

<Data></Data>

<Filter></Filter>

</Receiver>

</Receivers>

</Elements>

Gostaria de destacar algumas propriedades interessantes do arquivo “Elements.xml”:

§ ListTemplateId: É o id do tipo de lista, abaixo listo as principais:

o 100 - GenericList

o 101 - DocumentLibrary

o 102 - Survey

o 103 - Links

o 104 - Announcements

o 105 - Contacts

o 106 - Events

o 107 - Tasks

o Lista completa: http://msdn.microsoft.com/en-us/library/ms431081.aspx

§ Type : É o tipo de Evento que aquele Receiver corresponde.

§ SequenceNumber: Nº aleatório do Receiver, deve ser superio a 10000, pois até esse número está reservado pela Microsoft.

§ Assembly: Contém as informações da assembly publicada anteriormente no GAC.

§ Class: É a classe que contém o método que vai ser executado pelo EventReceiver.

14 – Publicando a feature.

Após a criação desses dois arquivos (Feature.xml e Elements.xml), agora basta navegar até a pasta raiz das features no SharePoint (C:/Program Files/Common Files/Microsoft Shared/web server extensions/12/TEMPLATE/FEATURES) e criar uma pasta para armazenar a feature (ex: MeuEventReceiver) e copiar os 2 arquivos lá.

15 – Instalando a feature.

§ Execute o seguinte comando na ferramenta STSADM

STSADM -o installfeature -name MeuEventReceiver

Obs.: Caso não saiba como utilizar o STSADM, acesse:

Stsadm command-line tool

http://technet.microsoft.com/en-us/library/cc261956.aspx

16 – Activando a feature.

Existem várias formas de se ativar uma feature, também podemos ativar via linha de comando (STSADM), porém acho mais fácil via interface com a aplicação, para isso siga os passos:

§ No site que deseja ativar a feature, clique no menu “Site Actions/Site Settings”.

§ Na janela de configuração, clique em “Site Administration/Site features”.

§ Note que a feature com o nome preenchido no arquivo “feature.xml”, está disponível, pronta para ser ativada.

§ Clique no botão Ativar.

§ Reinicie o IIS (Executar/IISRESET)

Conclusão

Agora pode testar a aplicação, se ocorrer tudo bem, ao adicionar novos itens na sua lista, verifique que o campo “MeuID” será preenchido pelo seu Event Receiver, também tente excluir um item de lista e verifique que irá aparecer a mensagem de erro configurada acima.

É claro que devemos levar em consideração que nosso exemplo foi bem simples e visava apenas explorar os Event Receivers, você deve ajustar tudo isso para seu contexto de projeto, nesse exemplo mesmo, todas as listas customizadas no site que a feature foi ativada irão tentar executar essas ações. ;)