Implantar recursos personalizados para conjuntos de sites atualizados no SharePoint Server 2013

APLICA-SE A:2013 2019 Subscription Edition SharePoint no Microsoft 365

Este artigo descreve como implantar recursos personalizados por meio de pacotes de solução em um farm do SharePoint Server 2013 que foi atualizado do SharePoint Server 2010. Ele inclui informações e procedimentos para cenários suportados. Além disso, introduz o mascaramento de recurso.

Coisas que você precisa saber

Esta seção descreve as informações de pré-requisito que você precisa saber antes de começar. Isso inclui o seguinte:

Quem precisa ler isso e por que

Este artigo é para profissionais de TI que devem trabalhar com desenvolvedores para implantar e manter recursos personalizados baseados em código de confiança total em várias coleções de sites em um farm do SharePoint Server 2013. Para saber como você pode usar recursos personalizados herdados ao atualizar para o SharePoint 2013 e o que fazer para ajudar a garantir que eles funcionem perfeitamente para seus usuários quando as coleções de sites forem atualizadas do modo de compatibilidade, consulte este artigo. Ele faz conexões com artigos adicionais que fornecem mais detalhes para os desenvolvedores.

Depois que um farm do SharePoint Server 2010 for atualizado para o SharePoint Server 2013, todas as coleções de sites são executadas no modo de compatibilidade do SharePoint 2010. Eles permanecem nesse modo até que cada coleção de sites seja atualizada para o modo SharePoint 2013. Dessa forma, seus usuários podem usar a interface do usuário do SharePoint Server 2010 e a funcionalidade com as quais estão familiarizados até que você atualize a coleção de sites individual. Você também pode usar os recursos personalizados herdados que você pode ter usado no SharePoint Server 2010. Eventualmente, você deseja atualizar suas coleções de sites para o modo SharePoint 2013 para aproveitar os novos recursos e funcionalidades que ele fornece. Quando fizer essa atualização, recursos personalizados que funcionavam no modo de compatibilidade do SharePoint 2010 podem não funcionar mais. Você precisa ter certeza de que existe uma continuidade entre modos do SharePoint com os mesmos recursos que estão sendo usados​​. Este artigo descreve como fazer isso.

Cmdlets do Microsoft PowerShell que você deve conhecer

Para os fins deste artigo, você deve estar familiarizado com os seguintes cmdlets do Microsoft PowerShell:

Nome	O que isso faz?	Exemplo
Add-SPSolution	Adiciona a solução ao repositório de soluções do farm.	Add-SPSolution -LiteralPath c:\contoso_solution.wsp
Install-SPSolution	Implanta uma solução que foi adicionada ao repositório de soluções do farm.	Install-SPSolution -Identity contoso_solution.wsp -GACDeployment -CompatibilityLevel 15
Uninstall-SPSolution	Retrai uma solução implantada.	Uninstall-SPSolution -Identity contoso_solution.wsp
Remove-SPSolution	Remove uma solução implantada.	Remove-SPSolution -Identity contoso_solution.wsp

Visão geral da implantação de um pacote de soluções

Para entender as seguintes seções, você deve entender como um recurso personalizado é implantado em um farm do SharePoint 2013.

Quando você atualiza do SharePoint Server 2010 para um farm do SharePoint 2013, adicionar seus recursos personalizados é uma etapa importante.

Figura: Adicionar recursos personalizados no processo de atualização

Você pode usar um pacote de solução para adicionar suas personalizações ao novo farm. Um pacote de solução é um pacote de distribuição que fornece seu trabalho de desenvolvimento personalizado do SharePoint 2013 para os servidores Web ou os servidores de aplicativo em seu farm de servidores. Você pode usar soluções para empacotar e implantar recursos personalizados, modelos de site, modelos de web, páginas de layout, web parts, folhas de estilo em cascata e trabalhos de timer.

Para implantar um pacote de solução a um farm do SharePoint 2013, você precisa:

1. Adicionar o pacote de solução a um farm. Use o cmdlet Add-SPSolution PowerShell para carregar o pacote de solução do SharePoint no farm. Isso adiciona a solução ao repositório de soluções do farm, localizado no banco de dados de configuração do farm.

2. Implantar o pacote de solução para o farm. Use o cmdlet Install-SPSolution PowerShell para implantar o pacote de solução do SharePoint no farm. Isso descompacta o pacote de solução e copia todos os arquivos contidos com um recurso personalizado para um diretório "Recurso" localizado no servidor Web front-end do farm. Uma subpasta para cada recurso personalizado é criada e inclui um arquivo Feature.xml. Este arquivo define as propriedades base do recurso e os elementos associados a ele, bem como um ou mais arquivos de manifesto de elemento (elements.xml) que definem os elementos que compõem o recurso.

O cmdlet Install-SPSolution PowerShell também inclui um parâmetro de nível de compatibilidade para implantar o pacote de solução em locais na pasta raiz que são designados para o modo SharePoint 2010 ou coleções de sites do modo SharePoint 2013. Estas são as pastas raiz "14" e "15" (hives) e, quando você implanta a solução, arquivos como recursos, arquivos de layout, imagens e modelos de controle são adicionados aqui.

Figura: Pastas raiz do SharePoint 2010 e 2013

Você também deve estar ciente de que, ao implantar um pacote de solução em um farm do SharePoint 2013, alguns arquivos são copiados para locais específicos, independentemente do nível de compatibilidade. Para obter mais detalhes sobre para onde os arquivos são copiados, consulte Planejamento de implantação de soluções farm para SharePoint 2013.

Os conjuntos de sites dos dois modos apontam para seu hive correspondente, de modo que eles possam usar os recursos personalizados fornecidos no pacote de solução.

Figura: Implantar recursos personalizados herdados após atualizar para o SharePoint Server 2013

O recurso personalizado pode ter sido testado para funcionar corretamente em ambos os modos do SharePoint 2010 e do SharePoint 2013. Em caso afirmativo, os arquivos do assembly de recurso podem ser idênticos. Por exemplo, se o recurso personalizado, Feature1, é conhecido por funcionar nos modos SharePoint 2013 e SharePoint 2010, o mesmo pacote de solução pode ser usado para implantar o mesmo recurso personalizado (Feature1) nas pastas "14" e "15".

No entanto, se o teste mostrar que o recurso personalizado herdado pode não funcionar em conjuntos de sites no modo do SharePoint 2013, você pode precisar fazer as seguintes alterações:

• Atualizar o pacote de solução para incluir lógica condicional que ativa a funcionalidade baseada no modo de conjunto de sites do SharePoint.

• Criar um novo e separado pacote de solução com funcionalidade atualizada para o recurso quando ele é usado por conjuntos de sites atualizados.

Mascaramento de recurso envolve o uso de um novo e separado pacote de solução para o mesmo recurso para sites e conjuntos de sites atualizados (quando um recurso tem como escopo um site ou um conjunto de sites). O mascaramento de recurso permite que os conjuntos de sites atualizados encontrem e utilizem automaticamente os assemblies de recurso personalizado corretos. Desta forma, os usuários podem facilmente usar o mesmo recurso personalizado.

Os recursos personalizados herdados em um farm do SharePoint Server 2013

Ao usar recursos personalizados herdados em um farm do SharePoint 2013, você pode se deparar com uma das três situações a seguir:

• O recurso personalizado fornecido pelo pacote de solução atualmente funciona para conjuntos de sites no modo do SharePoint 2010. Ele também funciona para coleções de sites no modo SharePoint 2013.

• O recurso personalizado fornecido pelo pacote de solução atualmente funciona para conjuntos de sites no modo do SharePoint 2010. Ele também funciona para coleções de sites no modo SharePoint 2013. Você também deve considerar a funcionalidade de recurso personalizado adicional que talvez queira adicionar incrementalmente no futuro para coleções de sites no modo SharePoint 2013.

• O recurso personalizado fornecido pelo pacote de solução atualmente funciona para conjuntos de sites no modo do SharePoint 2010. Mas não funciona para coleções de sites no modo SharePoint 2013.

Cenários com suporte

Ao implantar recursos personalizados em um farm do SharePoint 2013 que foi atualizado do SharePoint Server 2010, três cenários de implantação diferentes são suportados:

Cenário 1	Solução herdada para o modo de compatibilidade do SharePoint 2010 e funcionalidade para manter-se a mesma quando atualizada para o SharePoint 2013.
Cenário 2	Solução legada para o modo de compatibilidade do SharePoint 2010, mas recriou a solução para adicionar incrementalmente a funcionalidade para o modo do SharePoint 2013.
Cenário 3	Solução herdada para o modo de compatibilidade do SharePoint 2010, e compilar uma nova solução para implementar novas funcionalidades para o SharePoint 2013.

Cenário 1: Solução herdada para o modo de compatibilidade do SharePoint 2010 e espera-se que a funcionalidade se mantenha a mesma quando atualizada para o SharePoint 2013

Neste cenário, o recurso personalizado fornecido por meio do pacote de solução atualmente funciona corretamente em conjuntos de sites no modo de compatibilidade do SharePoint 2010. Além disso, espera-se que funcione quando a coleção de sites for atualizada para o modo SharePoint 2013. Por exemplo, uma Web Part personalizada foi criado para o SharePoint 2010. Ele foi testado para funcionar no SharePoint 2013 sem uma alteração no código. Você sabe que pode adicioná-lo ao farm do SharePoint 2013 e funciona para usuários em coleções de sites no modo de compatibilidade do SharePoint 2010 e quando você atualiza o site para o SharePoint 2013.

Como se espera que o recurso personalizado funcione em ambos os modos do SharePoint, você pode usar os mesmos assemblies de recurso personalizado. No entanto, é importante implantar o pacote de solução para ambos os modos do SharePoint, o que você pode fazer com um parâmetro quando estiver usando o cmdlet Install-SPSolution . O mascaramento de recurso não é usado neste cenário porque os conjuntos de sites em ambos os modos usam o mesmo código (assemblies de recursos duplicados localizados nas pastas do modo 2010 e 2013 correspondentes).

As etapas deste cenário incluem o seguinte:

1. Criar o pacote de solução que contém o recurso personalizado.

2. Adicionar o pacote de solução ao farm. Você pode fazer isso por meio do cmdlet Add-SPSolution PowerShell. Por exemplo:

   Add-SPSolution -LiteralPath c:\Solution.wsp

3. Implantar o pacote de solução.

4. Implante o pacote de solução para compatibilidade com o SharePoint 2010. Você pode fazer isso usando o cmdlet Install-SPSolution PowerShell. Defina o parâmetro -CompatibilityLevel como 14. Por exemplo:

   Install-SPSolution -Identity Solution.wsp -CompatibilityLevel 14 -GAC ...

5. Implante o pacote de solução para compatibilidade do SharePoint 2013. Você pode fazer isso usando o cmdlet Install-SPSolution PowerShell. Defina o parâmetro -CompatibilityLevel como 15. Por exemplo:

   Install-SPSolution -Identity Solution.wsp -CompatibilityLevel 15 -GAC ...

Cenário 2: Solução herdada para o modo de compatibilidade do SharePoint 2010, mas foi reconstruída a solução para adicionar funcionalidades de forma incremental ao SharePoint 2013

Nesse cenário, o recurso personalizado funciona corretamente no SharePoint Server 2010. Você deseja criar um pacote de solução adicionando esse recurso a um farm do SharePoint 2013, mas também deseja garantir que você possa adicionar incrementalmente funcionalidade para coleções de sites no modo SharePoint 2013 que estão usando esse pacote de solução. Por exemplo, uma Web Part personalizada foi criado para o SharePoint 2010. Ele foi testado para funcionar no SharePoint 2013 sem uma alteração no código. No entanto, você sabe que talvez queira adicionar funcionalidades adicionais para seus usuários do SharePoint 2013, mas ainda deseja usar os mesmos assemblies de recursos para permitir a compatibilidade anterior.

Como se espera que o recurso personalizado funcione em ambos os modos do SharePoint, você pode usar os mesmos assemblies de recurso personalizado. Você deve instalar o pacote de solução para ambos os modos do SharePoint como fez para o cenário anterior. A principal diferença nesse cenário é que o pacote de solução deve incluir lógica que permite a funcionalidade de recurso que se baseia condicionalmente na compatibilidade do conjunto de sites.

Por exemplo, digamos que você tenha um método chamado Sample() implementado em um recurso personalizado que foi projetado para o SharePoint 2010. Se você quiser alterar sua implementação no modo SharePoint 2013, seu código deverá incluir a lógica condicional que usa a propriedade SPSite.CompatibilityLevel:

void Sample()
{
if (site.CompatibilityLevel == 14) { /*Existing O14 implementation*/}
else {/*New O15 implementation*/}}
}

Ao fazer isso, o mesmo assembly de recursos serve tanto as versões do SharePoint 2010 quanto do SharePoint 2013 do recurso. O mascaramento de recursos também não é usado nesse cenário porque você não está apenas usando o mesmo assembly de recursos, mas também o mesmo pacote de solução. Os mesmos arquivos do recurso personalizado são copiados para os diretórios "14" e "15" \Template\Features. Para obter mais informações, confira a seção "Considerações de planejamento" da postagem no blog do TechNet, Planejamento da Implantação de Soluções Farm para SharePoint 2013.

As etapas deste cenário incluem o seguinte:

1. Crie o pacote de solução que contém o recurso personalizado. Inclua lógica condicional que habilite a funcionalidade do recurso com base na compatibilidade do conjunto de sites.

2. Adicione o pacote de solução ao farm. Você pode fazer isso usando o cmdlet Add-SPSolution PowerShell. Por exemplo:

   Add-SPSolution -LiteralPath c:\Solution.wsp

3. Implantar o pacote de solução.

4. Implante o pacote de solução para compatibilidade com o SharePoint 2010. Você pode fazer isso usando o cmdlet Install-SPSolution PowerShell. Defina o parâmetro -CompatibilityLevel como 14. Por exemplo:

   Install-SPSolution -Identity Solution.wsp -CompatibilityLevel 14 -GAC ...

5. Instale o pacote de solução para compatibilidade do SharePoint 2013. Você pode fazer isso usando o cmdlet Install-SPSolution PowerShell. Defina o parâmetro -CompatibilityLevel como 15. Por exemplo:

   Install-SPSolution -Identity Solution.wsp -CompatibilityLevel 15 -GAC ...

Cenário 3: Solução herdada para o modo de compatibilidade do SharePoint 2010 e compilar uma nova solução para implementar novas funcionalidades para SharePoint Server 2013

Nesse cenário, o recurso personalizado é conhecido por funcionar corretamente no SharePoint Server 2010, mas é conhecido por não funcionar no SharePoint 2013. Você precisa criar um pacote de solução novo e separado no qual a funcionalidade do recurso personalizado foi corrigida para funcionar corretamente no SharePoint 2013. Neste cenário, você tem dois pacotes de solução diferentes, com diferentes assemblies de recurso. Este cenário utiliza o mascaramento de recurso. À medida que os usuários são movidos do modo de compatibilidade para o SharePoint 2013, eles são "mascarados" do fato de que o recurso personalizado que estão usando mudou de uma base de código diferente para outra.

Neste cenário, você precisa adicionar e implantar dois pacotes de solução separados que contêm dois assemblies de recursos diferentes. Ambas as versões do recurso devem ter o mesmo nome, a ID do recurso e o local do manifesto de recurso, embora os assemblies de recurso e os recursos sejam diferentes.

Requisitos de mascaramento de recurso

Requisito	Mesmo ou diferente	Pacote de solução – exemplo do modo de 2010	Pacote de solução – exemplo do modo de 2013
Nomes de pacote de solução	Diferente	POC14	POC15
IDs de pacote de solução	Diferente	000000-0000-0000-0000-000000000000	11111111-1111-1111-1111-111111111111
Nome do recurso	Mesmo	Feature1	Feature1
ID do recurso	Mesmo	12345	12345
Nomes de pasta XML de recurso	Mesmo	POC15\Features\Feature1.feature\	POC15\Features\Feature1.feature\
Local de manifesto de recurso	Mesmo	POC15_Feature1\Feature1.Template.xml	POC15_Feature1\Feature1.Template.xml

Figura: Pacotes de solução para o mascaramento de recursos

As etapas deste cenário incluem o seguinte:

1. Criar dois pacotes de soluções diferentes, com nomes diferentes. As versões do recurso que você está implantando devem ter o mesmo nome de recurso e ID.

2. Adicione o pacote de solução de compatibilidade com o SharePoint 2010 ao farm. Você pode fazer isso por meio do cmdlet Add-SPSolution PowerShell. Por exemplo:

   Add-SPSolution -LiteralPath c:\POC14.wsp

3. Adicione o pacote de solução para a compatibilidade do SharePoint 2013 ao farm. Você também pode fazer isso por meio do cmdlet Do PowerShell do Add-SPSolution . Por exemplo:

   Add-SPSolution -LiteralPath c:\POC15.wsp

4. Implante o pacote de solução para a compatibilidade com o SharePoint 2010. Você pode fazer isso por meio do cmdlet Install-SPSolution PowerShell. Defina o parâmetro -CompatibilityLevel como 14. Por exemplo:

   Install-SPSolution -Identity POC14.wsp -CompatibilityLevel 14 -GAC ...

5. Instale o pacote de solução para compatibilidade do SharePoint 2013. Você também pode fazer isso por meio do cmdlet Install-SPSolution PowerShell. Defina o parâmetro -CompatibilityLevel como 15. Por exemplo:

   Install-SPSolution -Identity POC15.wsp -CompatibilityLevel 15 -GAC ...

Desinstalar um pacote de solução

Você não irá mais precisar do pacote de solução herdado que você implantou para os conjuntos de site do modo de compatibilidade do SharePoint 2010, uma vez que todos os conjuntos de sites foram atualizados para o modo do SharePoint 2013. Quando isso acontece, o pacote de solução herdado pode ser cancelado e removido do seu farm do SharePoint Server 2013. Você pode fazer isso por meio dos cmdlets Desinstalação-SPSolution e Remove-SPSolution do PowerShell.

Cancelar e remover o pacote de solução:

1. Retraia o pacote de solução do modo SharePoint 2010 do farm: você pode fazer isso por meio do cmdlet Desinstalar-SPSolution Windows PowerShell. Por exemplo:

   Uninstall-SPSolution -Identity POC14.wsp -CompatibilityLevel 14

   Importante

   Use o parâmetro CompatibilityLevel para " 14 " para retrair o pacote de solução somente para o modo de compatibilidade 2010. Por exemplo: Uninstall-SPSolution POC14.wsp -CompatibilityLevel 14

2. Remova o pacote de solução do repositório de soluções do farm: você pode fazer isso por meio do cmdlet Remove-SPSolution PowerShell. Por exemplo:

   Remove-SPSolution -Identity POC14.wsp

Outras considerações

Esta seção inclui informações sobre considerações adicionais, incluindo o seguinte:

• Implantar um recurso em conjuntos de sites usando o modo misto

• Considerações da página mestra

Implantar um recurso em conjuntos de sites usando o modo misto

Se o seu recurso personalizado estiver no escopo de farm ou aplicativo Web, você pode implantá-lo, mesmo que nem todos os conjuntos de sites no farm ou aplicativos web tenham sido atualizados para o modo de compatibilidade do SharePoint 2013.

Para recursos com escopo de aplicativo Web, se a coleção de sites raiz não tiver sido atualizada, você não poderá ativar o recurso usando o cmdlet Install-SPSolution PowerShell. Em vez disso, você deve usar o site da Administração Central do SharePoint para ativar o recurso.

Considerações da página mestra

Em relação às personalizações de identidade visual, as páginas mestras personalizadas são redefinidas por padrão para seattle.master após uma atualização da coleção de sites no SharePoint 2013. Se você estiver usando o cenário de mascaramento de recursos, precisará redefinir todas as páginas mestras personalizadas criadas para coleções de sites do SharePoint 2013. Para obter detalhes sobre como fazer isso, consulte o artigo MSDN Use a atualização de recursos para aplicar novas páginas mestras do SharePoint Server 2013 ao atualizar do SharePoint 2010.

Confira também

Outros recursos

Criar um plano para personalizações atuais durante a atualização para o SharePoint 2013

SharePoint 2013 e SharePoint no pacote de soluções do Microsoft 365 para branding e provisionamento de sites

Problemas de identidade visual que podem ocorrer durante a atualização para o SharePoint 2013