Fornecer a aparência do SharePoint a seu suplemento hospedado pelo provedor

Artigo
04/08/2023

Este é o segundo de uma série de artigos sobre os fundamentos do desenvolvimento de suplementos do SharePoint hospedados no provedor. Primeiro, você deve estar familiarizado com o tópico Suplementos do SharePoint e o artigo de visão geral desta série:

Introdução à criação de suplementos do SharePoint hospedados pelo provedor

No artigo anterior desta série, você aprendeu a configurar um ambiente de desenvolvimento e a usar o Visual Studio para criar uma primeira " Olá, Mundo" suplemento de nível que expõe dados do SharePoint no aplicativo Web remoto do suplemento.

Neste artigo, começamos com uma solução de Suplemento do SharePoint que já foi criada. Ele inclui um aplicativo ASP.NET Web Forms e um banco de dados SQL Azure. Criamos isso para você porque esta série de artigos destina-se a se concentrar apenas em Suplementos do SharePoint. Você adicionará mais funcionalidade e integração do SharePoint ao suplemento com cada artigo desta série.

Conhecer o suplemento base

Não vamos ensiná-lo ASP.NET ou programação T-SQL nesta série, mas você precisa saber um pouco sobre os componentes remotos do suplemento antes de começarmos a integrá-lo ao SharePoint. O cenário do suplemento prevê uma cadeia de lojas de varejo e cada loja tem um site de equipe na assinatura do SharePoint Online da empresa-mãe. Quando um repositório instala o suplemento em seu site de equipe, o suplemento permite que eles integrem seus dados do SharePoint e experiência com dados no banco de dados da empresa-mãe. Cada instância do suplemento tem sua própria locação no banco de dados corporativo, e os usuários só podem interagir com dados corporativos associados ao seu repositório.

Crie sites de equipe para duas lojas na cadeia

Abra a página inicial do seu site do SharePoint Online e selecione o link Conteúdo do Site no início rápido. Na página Conteúdo do Site, role para baixo até ver o link novo subsite e selecione-o.
Na página Novo Site do SharePoint, preencha o formulário para um novo site de equipe inserindo esses valores (também mostrados na captura de tela a seguir):
- Título: Fabrikam Hong Kong Store
- URL: hongkong
Figura 1. Formulário para criar um novo subsite do SharePoint
Deixe todas as outras configurações com seus padrões e selecione Criar.

Explorar o suplemento

Vá a SharePoint_Provider-hosted_Add-Ins_Tutorials e selecione o botão Baixar ZIP para baixar o repositório em sua área de trabalho. Descompacte o arquivo.
Inicie o Visual Studio como administrador e abra BeforeSharePointUI.sln. Há três projetos na solução:
- ChainStore: o projeto Suplemento do SharePoint
- ChainStoreWeb: o aplicativo Web remoto
- ChainCorporateDB: o banco de dados do SQL Azure
Selecione o projeto ChainStore e, na janela Propriedades defina a propriedade URL do Site como a URL completa do site de equipe de Hong Kong: https://{YOUR_SHAREPOINT_DOMAIN}/hongkong/ (certifique-se de incluir o caractere "/" no final). Selecione Salvar. Em algum momento desse processo, você será solicitado a entrar em sua assinatura do SharePoint Online.
Clique com botão direito do mouse no nó da solução na parte superior do Gerenciador de Soluções e então selecione Definir Projetos de Inicialização.
Verifique se todos os três projetos estão definidos como Iniciar na coluna Ação.
Use a tecla F5 para implantar e executar o suplemento. O Visual Studio hospeda o aplicativo Web remoto no IIS Express e hospeda o banco de dados SQL no SQL Express. Ele também faz uma instalação temporária do suplemento em seu site de teste do SharePoint e executa imediatamente o suplemento. Você é solicitado a conceder permissões ao suplemento antes que sua página inicial seja aberta.
A página inicial do suplemento é semelhante à da Figura 2. Na parte superior, está o nome do site do SharePoint em que o suplemento está instalado. Esse é um efeito colateral de algum código de exemplo que o Office Developer Tools para Visual Studio gera. Você alterará isso em uma etapa posterior. A página tem áreas em que os dados das tabelas de banco de dados SQL Pedidos, Inventárioe Funcionários corporativos podem ser vistos. Essas tabelas estão inicialmente vazias.

Figura 2. Página inicial do suplemento do repositório de rede
Selecione o Formulário de Pedido na parte inferior da página para abrir um formulário de pedido. Insira alguns valores no formulário e então selecione Fazer Pedido. A captura de tela na Figura 3 mostra um exemplo. Parece que nada aconteceu, mas o código por trás do botão passa os valores para um procedimento armazenado com parâmetros no banco de dados SQL. O uso de procedimentos armazenados parametrizados protege o banco de dados contra ataques de injeção de SQL.

Figura 3. Formulário de pedido
Use o botão Voltar do navegador para voltar para a página inicial e, em seguida, selecione o botão Mostrar Pedidos. A página inicial é atualizada e seu pedido aparece na página semelhante à captura de tela na Figura 4.

Figura 4. Página Iniciar depois de selecionar Mostrar Pedidos

A tabela tem um campo locatário com a URL do seu site do SharePoint de teste como o valor. Isso não se refere à assinatura do SharePoint Online que às vezes é chamada de locatário. Em vez disso, cada instância do suplemento é um locatário distinto no banco de dados corporativo. Como não mais de uma instância de um suplemento pode ser instalada em um host específico da Web do SharePoint, a URL do host da Web pode ser usada como um discriminador de locatário no banco de dados. (Para obter uma atualização sobre a distinção entre o host da Web e o site de suplementos, consulte Suplementos do SharePoint.)

Todos os procedimentos armazenados no suplemento incluem o valor discriminador quando eles gravam ou leem do banco de dados. Isso garante que, quando um usuário seleciona Mostrar Pedidos (ou Mostrar Inventário ou Mostrar Funcionários), somente os dados associados ao repositório do usuário são recuperados do banco de dados. Esse design também garante que os usuários só possam fazer pedidos e adicionar funcionários para sua própria loja.

O aplicativo Web remoto obtém a URL da Web do host de um parâmetro de cadeia de caracteres de consulta que o SharePoint adiciona à URL da página inicial quando inicia o suplemento. Como o SSL está sendo usado, essa cadeia de caracteres de consulta é criptografada à medida que passa pela Internet para o aplicativo Web remoto.
Para encerrar a sessão de depuração, feche a janela do navegador ou interrompa a depuração no Visual Studio. Sempre que você seleciona F5, o Visual Studio retrai a versão anterior do suplemento e instala a mais recente.
Por padrão, o suplemento permanece instalado no host do SharePoint na Web entre as sessões de depuração Visual Studio. Para ver como os usuários finais o iniciariam após a instalação, abra o site do SharePoint de Hong Kong da Fabrikam em seu navegador e vá para a página Conteúdo do Site. Você verá o bloco do suplemento como está na captura de tela a seguir.

Figura 5. Iniciar bloco para o suplemento Chain Store

O bloco de inicialização do suplemento da Cadeia de Lojas na página de conteúdo do site com o nome e o ícone do suplemento.

Observação

Se você selecionar o bloco, a página inicial não será aberta porque Visual Studio fechará a sessão IIS Express quando você interromper a depuração.

Configurar o Visual Studio para reconstruir o banco de dados corporativo com cada sessão de depuração

Por padrão, o Visual Studio não recompilará o banco de dados DO SQL Express. Portanto, os pedidos e outros itens que você adiciona ao banco de dados em uma sessão de depuração ainda estão no banco de dados em sessões posteriores. É mais fácil começar com um banco de dados vazio sempre que você seleciona F5, portanto, siga estas etapas:

Clique com botão direito do mouse no projeto ChainCorporateDB e selecione Propriedades.
Abra a guia Depurar e habilite a opção Sempre recriar banco de dados.

Dar ao aplicativo Web remoto a aparência do SharePoint

Em alguns cenários, você deseja que suas páginas remotas tenham sua própria identidade visual, mas na maioria dos casos elas devem imitar a interface do usuário do SharePoint para que os usuários continuem se sentindo no SharePoint.

Adicionar a barra superior e o cromo do SharePoint à página inicial

No Gerenciador de Soluções, vá até ChainStoreWeb> Páginas e abra o arquivo CorporateDataViewer.aspx. Essa é página inicial do suplemento.

Na seção cabeçalho, você verá um script que carrega algumas bibliotecas JavaScript. Adicione o script adicional a seguir sob ele. Esse script carrega o arquivo SP.UI.Controls.js, que está em todos os sites do SharePoint na pasta /_layouts/15/. Entre outras coisas, esse arquivo carrega a biblioteca CSS do SharePoint.

  <script type="text/javascript">
    var hostweburl;

    // Load the SharePoint resources.
    $(document).ready(function () {

        // Get the URI decoded add-in web URL.
        hostweburl =
            decodeURIComponent(
                getQueryStringParameter("SPHostUrl")
        );

        // The SharePoint js files URL are in the form:
        // web_url/_layouts/15/resource.js
        var scriptbase = hostweburl + "/_layouts/15/";

        // Load the js file and continue to the 
        // success handler.
        $.getScript(scriptbase + "SP.UI.Controls.js")
    });

    // Function to retrieve a query string value.
    function getQueryStringParameter(paramToRetrieve) {
        var params =
            document.URL.split("?")[1].split("&amp;");
        var strParams = "";
        for (var i = 0; i < params.length; i = i + 1) {
            var singleParam = params[i].split("=");
            if (singleParam[0] == paramToRetrieve)
                return singleParam[1];
        }
    }
</script>

Na parte superior do corpo da página, adicione a marcação a seguir. Isso inserirá a barra superior do SharePoint, chamada de controle cromado, na página. Os detalhes dessa marcação ficarão mais claros quando testarmos o suplemento revisado mais tarde neste artigo (a cadeia de caracteres "app" aparece em alguns dos nomes de propriedade porque os suplementos costumavam ser chamados de "aplicativos").

  <!-- Chrome control placeholder. Options are declared inline.  -->
<div 
    id="chrome_ctrl_container"
    data-ms-control="SP.UI.Controls.Navigation"  
    data-ms-options=
        '{  
            "appHelpPageUrl" : "Help.aspx",
            "appIconUrl" : "/Images/AppIcon.png",
            "appTitle" : "Chain Store",
            "settingsLinks" : [
                {
                    "linkUrl" : "Account.aspx",
                    "displayName" : "Account settings"
                },
                {
                    "linkUrl" : "Contact.aspx",
                    "displayName" : "Contact us"
                }
            ]
         }'>
</div>

Os cabeçalhos H1 e o hiperlink no corpo da página usam automaticamente estilos definidos na biblioteca CSS do SharePoint, para que eles não precisem ser alterados. Para ilustrar como você pode usar os estilos do SharePoint, defina os títulos de coluna nos três controles GridView como "all caps" do SharePoint adicionando o atributo HeaderStyle-CssClass a cada um dos controles e definindo seu valor como ms-uppercase. Apresentamos um exemplo a seguir. Faça a mesma alteração em todos os três controles GridView.
```
  <asp:GridView ID="ordersGridView" runat="server" CellPadding="5" GridLines="None" 
HeaderStyle-CssClass="ms-uppercase" />
```
O controle de cromo usa o ícone do suplemento, portanto, precisamos de uma segunda cópia do arquivo de ícone no servidor Web remoto. No Gerenciador de Soluções, clique com o botão direito do mouse no arquivo AppIcon.png no projeto do ChainStore e selecione Copiar.
Clique com botão direito do mouse na pasta Imagens no projeto ChainStoreWeb e selecione Colar.
Abra o arquivo CorporateDataViewer.aspx.cs.
A CorporateDataViewer classe declara um membro privado do tipo SharePointContext. Essa classe é definida no arquivo SharePointContext.cs que as Ferramentas de Desenvolvedor do Office para Visual Studio geraram quando o projeto foi criado. Você pode pensar nela como algo como a classe HttpContextBase de ASP.NET, mas com informações contextuais do SharePoint, como a URL da Web do host adicionada a ela.

No método Page_Load, uma instruçãode uso grava o nome da Web host do SharePoint na página inicial remota. Esse é um código de exemplo, portanto, exclua toda a instrução de uso (mas deixe a linha que inicializa o spContextvariável). Agora o método deve ter a aparência a seguir.
```
  protected void Page_Load(object sender, EventArgs e)
{
    spContext = SharePointContextProvider.Current.GetSharePointContext(Context);
}
```
Há quatro outros arquivos ASP.NET que precisam da interface do usuário do SharePoint:
- Account.aspx
- Contact.aspx
- Help.aspx
- OrderForm.aspx
Observação

O último arquivo aspx no projeto, EmployeeAdder.aspx, nunca é realmente renderizado, portanto, você não altera sua interface do usuário. Você aprenderá mais sobre isso em um artigo posterior desta série.

Não queremos o controle de cromo nessas páginas. Queremos apenas acesso à biblioteca CSS do SharePoint. Para cada um desses quatro arquivos, adicione a marcação a seguir ao elemento cabeçalho.
```
  <link type="text/css" rel="stylesheet" 
href="<%= spContext.SPHostUrl.ToString() + "_layouts/15/defaultcss.ashx" %>" />
```
Esta etapa e a próxima já foram feitas para a página Formulário de Pedido e a página Conta, portanto, elas se aplicam somente à página Contato e à página Ajuda. Para colocar o spContext objeto em cada uma das páginas, abra o código *.aspx.cs atrás dos arquivos para as três páginas aspx. Em cada um deles, adicione o membro a seguir à classe Página.
```
  protected SharePointContext spContext;
```
Substitua o método Page_Load pela versão a seguir. O objeto está sendo recuperado do cache de sessão. Ele foi armazenado em cache quando foi criado pela primeira vez pelo método Page_Load da página inicial do suplemento.
```
  protected void Page_Load(object sender, EventArgs e)
{
    spContext = Session["SPContext"] as SharePointContext;
}
```
Abra a página OrderForm.aspx. No elemento Etiqueta superior, substitua o elemento <b> na frase Fazer Pedido por marcas de intervalo que fazem referência à classe CSS ms-accentText. Toda a Etiqueta deve ter esta aparência quando você terminar.
```
  <asp:Label ID="lblOrderPrompt" runat="server"
         Text="Enter a supplier, product, and quantity; and then press <span class='ms-accentText'>Place Order</span>.">
</asp:Label>
```

Executar o suplemento e testar a nova interface do usuário do SharePoint

Use a tecla F5 para implantar e executar o suplemento. O Visual Studio hospeda o aplicativo Web remoto no IIS Express e hospeda o banco de dados SQL no SQL Express. Ele também faz uma instalação temporária do suplemento em seu site de teste do SharePoint e executa imediatamente o suplemento. Você é solicitado a conceder permissões ao suplemento antes que sua página inicial seja aberta.
Quando a página inicial do suplemento é aberta, agora ela se parece com uma página do SharePoint. Selecione o link Formulário de Pedido. Agora também se parece com um formulário do SharePoint.

Figura 6. O Formulário de Pedido com fontes Segoe e um Pedido de Lugar realçado
Crie um pedido e, em seguida, selecione Fazer Pedido.
Use o botão Voltar do navegador para voltar para a página inicial do suplemento e, em seguida, selecione Mostrar Pedidos. A página agora deve ser semelhante à seguinte. Observe que os títulos de coluna agora estão todos em maiúsculas.

Figura 7. A página inicial com um controle cromado
Selecione o ícone ? no final do controle cromado. Uma página de ajuda simples é aberta. Selecione o botão Voltar do navegador.
Selecione o ícone de engrenagem no controle de cromo. Um menu é aberto com links para uma página de Conta e uma página de Contato. Abra a página Conta e use o botão Voltar do navegador para voltar à página inicial. Faça o mesmo para a página Contato.
Selecione o botão Voltar ao Site no controle de cromo. A página inicial do host da Web, o site de equipe da loja de Hong Kong, é aberto.
Selecione o ícone de engrenagem na barra superior e selecione Alterar a aparência.
Siga os prompts para alterar o site para uma das "aparências" alternativas.
Navegue até a página Conteúdo do Site e inicie o aplicativo Chain Store a partir de seu bloco. Suas páginas personalizadas assumiram o visual escolhido. As capturas de tela a seguir mostram como elas aparecem no visual composto pela Natureza .

Figura 8. A página inicial e o formulário de pedido com o visual composto pela Natureza

Página inicial de suplementos e formulário de pedido com cores esverdeadas da aparência composta Natureza.

Altere a aparência do site novamente para o padrão, que é chamado de Office.
Para encerrar a sessão de depuração, feche a janela do navegador ou interrompa a depuração no Visual Studio. Sempre que você seleciona F5, o Visual Studio retrai a versão anterior do suplemento e instala a mais recente.
Você lidará com esse suplemento e com a solução do Visual Studio em outros artigos, e recomenda-se retirar o suplemento uma última vez quando for deixar de trabalhar com ele por algum tempo. Clique com botão direito do mouse no projeto no Gerenciador de Soluções e escolha Retirar.

Próximas etapas

O suplemento agora se parece com o SharePoint, mas ainda é apenas um aplicativo Web que realmente não se integra ao SharePoint além de ser iniciado a partir de um bloco no SharePoint. Você adicionará um comando personalizado, iniciado a partir de um botão de faixa de opções personalizado no próximo artigo: Inclua um botão personalizado no suplemento hospedado pelo provedor.

Partilhar via