Gerenciando alterações na Web.Config com o SPWebConfigModification

Overview

Esse artigo vai abordar um cenário muito interessante de desenvolvimento mais avançado no SharePoint, vamos explorar o funcionamento de um objeto da API do SharePoint “SPWebConfigModification”, presente no namespace Microsoft.SharePoint.Administration.

Esse objeto traz uma funcionalidade que considero fantástica para apoiar nós Desenvolvedores SharePoint no processo de Deploy das nossas aplicações.

Uma tarefa comum para Desenvolvedores Web é adicionar/alterar/excluir seções como httpModules, httpHandler, appSettings, PageParserPaths, ConnectionStrings, Membership entre outras em um arquivo web.config.

O ponto é como realizar essas alterações de modo gerenciável e centralizado, imagine como poderíamos replicar essas alterações em web.config’s de todo o FARM com vários Web Front Ends em operação? Algumas alterações como SafeControls e CAS Policy já são gerenciadas pelos pacotes de solução do SharePoint (WSP) e os WSPs fazem esse papel de automatização, para as demais nós podemos utilizar a API do SharePoint que traz esse objeto SPWebConfigModification com exatamente esse papel, nesse modelo é possível automatizar uma implantação de aplicativos SharePoint que utilizem chaves customizadas no web.config e replicar essas alterações entre todos os Web Front Ends.

Veja mais informações em:

SPWebConfigModification Class (Microsoft.SharePoint.Administration)

How To: Modify the web.config file in SharePoint using SPWebConfigModification

ASP.NET Configuration Files

Solution Overview (WSP)

Creating a Solution

WSPBuilder (CodePlex)

Solução

Para essa solução vou trabalhar com os seguintes produtos e tecnologias:

Windows Server 2008 com SP1
Microsoft Office SharePoint Server 2007 com SP2
SQL Server 2008
Visual Studio 2008 + Extensions for Windows SharePoint Services 3.0, v1.2
Microsoft C#

INFO: Eu utilizei o MOSS 2007, mas o exemplo também se aplica ao WSS 3.0, o SPWebConfigModification é um objeto da API do Windows SharePoint Services 3.0.

O SPWebConfigModification é poderoso pelo seu modelo de automatização, mas como em todo modelo de automatização, nós devemos tomar alguns cuidados antes de iniciarmos a implantação de um recurso como esse que mal implantado, pode “derrubar” todo um farm.

Vamos explorar algumas propriedades do nosso objeto:

Name: Nome do atributo ou seção do node que será modificado/criado.
Owner: Dono da alteração na web.config, esse campo deve conter uma chave única do tipo string, a partir do “Owner” serão controladas todas as alterações no node informado. Importante dizer que esse node fica “bloqueado” para ser alterado apenas pelo Owner, é recomendado que essa propriedade seja preenchida com o nome da Assembly, Feature ou FeatureID.
Path: O Path é uma expressão XPath utilizada para localizar o node no web.config, ex: “system.web/httpModules”.
Sequence: Número da sequência da alteração, por padrão começa com 0.
Type: Nessa propriedade podemos definir 3 tipos de alteração: EnsureChildNode, EnsureAttribute, e EnsureSection, veja mais em SPWebConfigModificationType.
UpgradedPersistedProperties: Retorna a coleção de nomes e valores dos campos que foram deletados ou alterados.
Value: Atribui ou Retorna o valor do item configurado.

DICA: Muita atenção no campo Owner, pois o SPWebConfigModification “bloqueia” a alteração realizada no nó/seção/atributo, o SPWebConfigModification realiza a alteração na web.config da Web Application que foi configurada e salva a web.config no banco para replicar em todos os WFEs do FARM, ou seja, em qualquer alteração que ocorrer na Web Application o SharePoint vai sobrescrever a web.config novamente.

Para nossa solução, vou utilizar um exemplo muito comum de alteração no web.config em aplicações SharePoint, principalmente quando ela ainda se encontra em desenvolvimento que é a ativação dos erros detalhados no SharePoint, que substituem a mensagem de “Erro Desconhecido”.

No nosso exemplo vamos utilizar uma feature para controlar nossa solução, através dos métodos FeatureActivated e FeatureDeactivating, quando a feature for ativada nós iremos alterar a web.config para exibir os erros e quando for desativada a web.config volta ao seu estado padrão, siga os passos abaixo para ativar e desativar nossa solução no site.

1. Criando a classe SPWebConfigModification

1.1. No Visual Studio, clique “File/New/Project”.

1.2. Na janela New Project, clique em “Visual C#/SharePoint/Empty”, renomeie o campo “Name” para “CanalSharePoint.Artigos”.

Obs.: Eu utilizei um projeto do tipo “Visual C#/SharePoint/Blank”, mas poderia ser também um projeto do tipo “Visual C#/Class Library”.

1.3. Na janela Solution Explorer, clique com o botão direito no projeto, depois em “Add/Class” e então renomeie a classe para “CustomErrorActivated.cs”.

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

1.5. Importe para essa classe o namespace Microsoft.SharePoint.

using Microsoft.SharePoint

1.6. Herde a classe SPFeatureReceiver, porque queremos manipular os eventos da feature.

public class CustomErrorActivated: SPFeatureReceiver

1.7. Clique com o botão direito em SPFeatureReceiver e implemente a classe abstrata:

Após comentar as exceptions dos métodos não implementados, seu código deve ficar assim:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.SharePoint;

namespace CanalSharePoint.Artigos
{
    public class CustomErrorActivated : SPFeatureReceiver
    {
        public override void FeatureActivated(SPFeatureReceiverProperties properties)
        {
            //throw new NotImplementedException();
        }

        public override void FeatureDeactivating(SPFeatureReceiverProperties properties)
        {
            //throw new NotImplementedException();
        }

        public override void FeatureInstalled(SPFeatureReceiverProperties properties)
        {
            //throw new NotImplementedException();
        }

        public override void FeatureUninstalling(SPFeatureReceiverProperties properties)
        {
            //throw new NotImplementedException();
        }
    }
}

Agora vamos construir os métodos que vão utilizar a classe SPConfigModification. Vou utilizar o tipo EnsureAttribute porque o objetivo é alterar um atributo de uma seção no web.config, para outras opções vocês podem utilizar os tipos EnsureChildNode e EnsureSection, conforme descrito acima, nas propriedades da classe.

1.8. Importe o namespace Microsoft.SharePoint.Administration

using Microsoft.SharePoint.Administration;

1.9. Logo acima do método FeatureActivated, adicione o seguinte código:

private const string Owner = "CanalSharePoint.Artigos.CustomErrorActivated";
private static readonly SPWebConfigModification[] Mods = {           
    new SPWebConfigModification()
        {
            Name = "mode",
            Owner = Owner,                                      
            Type = SPWebConfigModification.SPWebConfigModificationType.EnsureAttribute,
            Path = "configuration/system.web/customErrors",
            Sequence = 0,                   
            Value = "Off"
        }
};

No código acima nós criamos o construtor da classe SPWebConfigModification com as configurações utilizadas no exemplo do artigo.

1.10. Logo abaixo do código acima, crie o método AddRemoveSPWebMod com o seguinte código:

private void AddRemoveSPWebMod(Boolean Activated)
 {
     using (SPSite site = new SPSite(SPContext.Current.Site.Url))
     {
         using (SPWeb web = site.OpenWeb())
         {
             SPWebApplication webApp = site.WebApplication;
             if (webApp != null)
             {
                 //Adicionando a nova WebConfigModification
                 foreach (SPWebConfigModification Mod in Mods)
                 {
                     if (Activated)
                     {
                         webApp.WebConfigModifications.Add(Mod);
                     }
                     else
                     {
                         webApp.WebConfigModifications.Remove(Mod);
                     }
                 }
                 // Salvando as alterações no Farm
                 webApp.Farm.Services.GetValue<SPWebService>().ApplyWebConfigModifications();
                 webApp.Update();
             }
         }
     }
 }

1.11. No método FeatureActivated, adicione o seguinte código:

public override void FeatureActivated(SPFeatureReceiverProperties properties)
        {
            AddRemoveSPWebMod(true);
        }

1.12. No método FeatureDeactivating, adicione o seguinte código:

public override void FeatureDeactivating(SPFeatureReceiverProperties properties)
        {
            AddRemoveSPWebMod(false);
        }

1.13. Compile a aplicação e elimine qualquer erro (CTRL+SHIFT+B).

1.14. 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.

1.15. Compile novamente a aplicação (CTRL+SHIFT+B).

Vamos iniciar o deploy da nossa DLL, normalmente você deverá realizar esse deploy seguindo o modelo de Features & Solutions do SharePoint, mas como esse não é o foco do artigo, vamos fazer de forma mais simples.

Para quem desejar ler mais sobre o modelo de Feature & Solutions, nesse mesmo artigo na seção de Overview eu disponibilizei alguns links falando sobre o assunto.

1.16. Copie a DLL (Pasta do Projeto\bin\Debug) gerada pelo seu projeto no GAC (C:\WINDOWS\assembly) do(s) seu(s) WFE (Web Front End).

Agora vamos criar a Feature que vai manipular nossa classe.

1.17. Crie uma nova Feature seguindo os passos:

a. Adicione um novo item ao projeto chamado feature.xml, do template “XML File”.
b. Adicione o seguinte código ao arquivo feature.xml:

<?xml version="1.0" encoding="utf-8" ?>
<Feature Id="F93016C4-2378-43D0-843C-2770B8334A55"
   Title="Gerenciando alterações na Web.Config com o SPWebConfigModification"
   Description="Feature criada para Ativar a demo da classe SPWebConfigModification"
   Version="1.0.0.0"
   Scope="Site"
   ReceiverAssembly="CanalSharePoint.Artigos, 
   		Version=1.0.0.0, Culture=Neutral, PublicKeyToken=9f4da00116c38ec5"
   ReceiverClass="CanalSharePoint.Artigos.CustomErrorActivated"
   xmlns="http://schemas.microsoft.com/sharepoint/" />

c. 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).

Obs.: Observem as propriedades da Feature, elas devem estar preenchidas corretamente, para maiores informaçãoes de Features no SharePoint, vejam: http://msdn.microsoft.com/en-us/magazine/cc163428.aspx.

1.18. Copie a feature para a pasta FEATURES.

Após a criação desse arquivo (feature.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), criar uma pasta para armazenar a feature (ex: CanalSharePoint.Artigos.SPWebConfig) e copiar o arquivo lá.

1.19. Instale a feature executando o seguinte comando STSADM:

STSADM -o installfeature -name CanalSharePoint.Artigos.SPWebConfig

1.20. Ative a Feature no site que deseja utilizar a classe SPWebConfigModification, para isso siga os passos:

1.21. No site clique no menu “Site Actions/Site Settings”.

1.22. Na janela de configuração, na seção “Site Collection Administration”, clique em “Site Collection features”.

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

1.23. Clique no botão “Activate”.

Após ativar sua feature, note que na web.config a seção customErrors o atributo mode terá seu valor alterado para “Off”, deverá ficar assim:

<customErrors mode="Off" />

Ao desativar a feature, sua web.config será restaurada com o valor anterior nessa seção.

Conclusão

Nesse artigo nós exploramos um recurso muito interessante, que pode ajudar bastante nós desenvolvedores a gerenciar e automatizar alterações na web.config.

Para quem desejar, disponibilzei o código do artigo.

Desenvolvimento - Sharepoint - Dev

Leia também