OneDrive for Business personalização no modelo de suplemento do SharePoint

A abordagem que você adota para personalizar OneDrive for Business sites no novo modelo de Suplemento do SharePoint é diferente do que era com o Código de Confiança Total. Em um cenário típico de FTC (Código de Confiança Total) /Farm Solution, os Trabalhos de Temporizador do SharePoint foram criados com o código modelo de objeto lateral do SharePoint Server, implantado por meio de Farm Solutions e gerenciados no site da Administração Central do SharePoint. O SharePoint manipula o agendamento e a execução do trabalho de temporizador nesse cenário.

Em um cenário de modelo de suplemento do SharePoint, os trabalhos de temporizador são criados e agendados fora do SharePoint. O SharePoint não é responsável pelo agendamento ou pela execução do trabalho de temporizador neste cenário.

Por que você personalizaria OneDrive for Business sites?

Há vários aspectos diferentes sobre como aplicar a personalização a sites de OneDrive for Business (OD4B). Você certamente pode personalizar esses sites, pois eles são sites do SharePoint, mas, ao mesmo tempo, você deve sempre considerar o impacto de curto e longo prazo da personalização.

Diretrizes de alto nível

Como regra geral, gostaríamos de fornecer as diretrizes de alto nível a seguir para personalizar sites OD4B.

• Aplicar personalização de identidade visual usando temas Office 365 ou mecanismo de temas do site do SharePoint
• Se os mecanismos de tema não forem suficientes, você poderá ajustar algumas configurações do CSS usando a opção CSS alternativa
• Evite personalizar sites OD4B usando páginas de master personalizadas, pois isso causará custos e desafios adicionais a longo prazo com atualizações futuras
  • Na maioria dos casos, você pode alcançar todos os cenários comuns de branding com temas e CSS alternativos, portanto, isso não é realmente esse fator limitante
  • Se você optar por usar páginas de master personalizadas, prepare-se para aplicar alterações nos sites quando as principais atualizações funcionais forem aplicadas a Office 365
• Você pode usar a inserção javaScript para modificar ou ocultar a funcionalidade no site
• Você pode usar o CSOM para controlar, por exemplo, o idioma ou as configurações regionais nos sites OD4B (confira novas APIs)
• Não recomendamos o uso de tipos de conteúdo e colunas de site em sites OD4B para evitar desafios com os campos necessários ou outros elementos, o que poderia causar problemas para casos de uso normais com sites OD4B
  • Pense em sites OD4B como para dados e documentos não estruturados pessoais. Sites de equipe e colaboração são então para dados da empresa e documentos em que você certamente pode usar quaisquer políticas de gerenciamento de informações e metadados desejados.

Como resumo, a personalização é definitivamente compatível com Office 365 e você pode continuar usando-os com sites OD4B. Queremos realmente garantir que você considere o impacto a curto e longo prazo da personalização da perspectiva operacional e de manutenção. Isso não é realmente específico para o SharePoint, mas sim uma regra geral para qualquer build de solução de TI com qualquer plataforma.

Aqui está um exemplo do site OD4B, que foi personalizado usando diretrizes acima. Nesse caso, o resultado final foi obtido com a combinação de temas Office 365, tema do site e uso do chamado padrão de inserção JavaScript.

Desafio ao aplicar as personalizações de site do OneDrive for Business

Vamos começar definindo qual é o desafio e o que estamos tentando resolver aqui. Tecnicamente, cada site OneDrive for Business está usando arquitetura idêntica como o que o pessoal ou meus sites usaram na versão do SharePoint 2007 ou 2010. Isso significa que, tecnicamente, cada site OneDrive for Business é sua própria coleção de sites e não temos nenhum local centralizado para aplicar a identidade visual ou quaisquer outras personalizações.

A solução clássica para aplicar a configuração necessária aos sites de OneDrive for Business (incluindo meus sites pessoais) foi baseada na stapling de recursos no nível do farm. Isso significava que você implantou a solução farm em seu farm do SharePoint e usou a estrutura de recursos para associar seu recurso personalizado a ser ativado sempre que um site é engradado, o que foi então responsável pela aplicação das personalizações necessárias. Essa abordagem semelhante não funciona em Office 365, pois requer que a solução farm seja implantada e isso é simplesmente impossível com Office 365 sites. Portanto, precisamos procurar alternativas para aplicar as alterações necessárias aos sites.

Em Office 365 não há nenhum evento centralizado gerado, ao qual poderíamos anexar nosso código personalizado quando o site OD4B for criado. Isso significa que precisamos pensar em soluções alternativas, o que é bastante comum com abordagens de modelo de aplicativo. Não fique preso em modelos antigos, pense em como alcançar o mesmo resultado final usando novas APIs e tecnologias. Do ponto de vista de requisito puro, realmente não importa como aplicamos as personalizações aos sites, desde que sejam aplicadas, já que o requisito comercial é não usar o stapling de recursos, trata-se de aplicar personalizações necessárias usando qualquer mecanismo técnico compatível.

Opções diferentes para aplicar a personalização

Na prática, temos quatro mecanismos diferentes para aplicar a personalização centralizada a sites OD4B no Office 365. Você também pode considerar a opção manual como a quinta, mas no caso de ter centenas ou milhares de sites OD4B, usar opções manuais não é realmente uma opção realista. Aqui estão as diferentes opções que temos.

1. Configurações de nível do pacote Office 365 (temas do Office 365 e outras configurações)
2. Ocultar parte do aplicativo com contexto de usuário
3. Criar previamente e aplicar a configuração
4. Trabalho de temporizador remoto com base em atualizações de perfil de usuário

Cada uma das opções tem vantagens e desvantagens nelas e a opção certa depende de seus requisitos comerciais detalhados. Algumas das configurações também podem ser aplicadas no nível do pacote Office 365, mas muitas vezes você estaria procurando algumas mais específicas, portanto, personalizações reais são necessárias. Obviamente, tudo se resume a requisitos exatos e análises de casos de negócios sobre seu impacto no curto e longo prazo.

Configurações de nível do pacote do Office 365

Office 365 é muito mais do que apenas o SharePoint, como você sabe. Você pode encontrar cada vez mais serviços adicionais que não se baseiam nem na arquitetura do SharePoint, como Delve, Yammer e muitos serviços futuros. Isso significa que a identidade visual e a configuração da empresa não se trata apenas de controlar o que temos nos sites do SharePoint, mas sim pensar na experiência geral do usuário final e como fornecemos configurações consistentes entre diferentes serviços.

O exemplo clássico desses requisitos empresariais é a identidade visual e, para isso, já Office 365 temas introduzidos, que podem ser usados para controlar algum nível de identidade visual. Também temos outros recursos futuros, que ajudarão a controlar a governança do site e outras configurações, do local centralizado fora das configurações de coleção de sites, como o próximo Centro de Conformidade para Office 365, que atualmente está listado no roteiro Office 365.

A imagem a seguir mostra as diferentes configurações agora para o Office 365 temas, que serão aplicados entre todos os serviços Office 365.

Como por padrão Office 365 configurações de tema são para controlar a barra de pacotes de sites OD4B, você provavelmente usará essas opções junto com outras opções para garantir que você possa fornecer pelo menos os elementos de identidade visual certos entre seus sites OD4B. Observe que quando você altera, por exemplo, Office 365 configurações de tema em Office 365 ferramenta de administrador, leva muito tempo para obter as configurações aplicadas para sites OD4B, portanto, tenha paciência.

Ocultar parte do aplicativo com contexto de usuário

Essa é uma abordagem em que o uso da página de destino centralizada é o local para iniciar o processo de personalização necessário. Isso significa que você teria que ter um local centralizado, como a primeira página da intranet da empresa, em que os usuários estão sempre pousando quando abrem o navegador. Esse é um processo bastante típico com empresas de médio e maior porte, em que a página de destino corporativa é controlada usando configurações de política de grupo no AD. Isso garantirá que os usuários finais não possam substituir a página de boas-vindas padrão dos navegadores ingressados no domínio da empresa.

Quando o usuário chegar à intranet, teremos a parte oculta do aplicativo na página, que iniciará o processo de personalização. Ele também pode ser responsável por toda a criação do site OD4B, já que normalmente o usuário teria que visitar o site OD4B uma vez, antes que o processo de criação do site seja iniciado. A parte do aplicativo oculto está, na verdade, hospedando uma página do aplicativo hospedado do provedor hospedado no Azure. Essa página é então responsável por iniciar o processo de personalização.

Vamos dar uma olhada mais de perto no design lógico dessa abordagem.

1. Coloque a parte do aplicativo oculto no site centralizado onde os usuários finais pousarão. Normalmente essa é a página de entrada da intranet corporativa.
2. A parte do aplicativo está hospedando uma página do aplicativo hospedado do provedor, onde no código lateral do servidor iniciamos o processo de personalização adicionando metadados necessários à fila de armazenamento do azure. Isso significa que esta página receberá apenas a solicitação de personalização, mas não aplicará nenhuma alteração para manter o tempo de processamento normal.
3. Essa é a fila de armazenamento do azure real, que receberá as mensagens na fila para processamento. Dessa forma, podemos lidar com o processo de controle de personalização de forma assíncrona para que ele realmente não importe quanto tempo o usuário final permanecerá na primeira página da Intranet. Se o processo de personalização for síncrono, dependeremos do usuário final para manter o navegador aberto na primeira página da Intranet até que a execução da página seja finalizada. Isso definitivamente não seria ideal e foi o desafio com o processo de personalização OD4B original, que eu blogged enquanto estava de volta.
4. WebJob fisgou para seguir a fila de armazenamento, que é chamada quando o novo item é colocado na fila de armazenamento. Este WebJob receberá os parâmetros e metadados necessários da mensagem enfileirada para acessar a coleção de sites correta. O WebJob está usando apenas o token de aplicativo e recebeu as permissões necessárias para manipular coleções de sites no nível do locatário.
5. As personalizações reais são aplicadas um por um aos sites dessas pessoas que visitam a primeira página da intranet para iniciar o processo.

Este é definitivamente o processo mais confiável de garantir que haja configurações corretas nos sites OD4B. Você pode adicionar facilmente a lógica de versão de personalização ao processo, que também está aplicando todas as atualizações necessárias aos sites OD4B, quando há uma atualização necessária e o usuário visita a primeira página da Intranet na próxima vez. No entanto, essa opção exige que você tenha aquele local centralizado onde os usuários finais estão pousando.

Se você estiver familiarizado com modelos clássicos de desenvolvimento do SharePoint com soluções farm, este é um processo bastante semelhante ao de executar trabalhos de temporizador uma vez.

Criar previamente e aplicar a configuração

Essa opção depende da pré-criação dos sites OD4B antes que os usuários os acessem. Isso pode ser obtido usando uma API relativamente nova que nos fornece para criar sites OD4B para usuários específicos em processo de lote, usando CSOM ou REST. O código necessário pode ser iniciado usando um script do PowerShell ou escrevendo um código real que está chamando as APIs remotas.

1. O administrador está usando as APIs de criação remota para criar sites OD4B para usuários e está aplicando as personalizações necessárias aos sites OD4B como parte do processo de script.
2. Sites OD4B reais são criados para o Office 365 para usuários específicos e associados aos seus perfis de usuário

Em algum sentido, esse também é um processo realmente confiável, mas você teria que gerenciar novas pessoas e atualizações "manualmente", o que poderia significar mais trabalho do que usar a abordagem de parte do aplicativo oculto . Essa é definitivamente uma abordagem válida que pode ser tomada e especialmente útil se você estiver migrando de alguma outra solução de compartilhamento de arquivos para o OD4B e quiser evitar a necessidade de usuários finais acessarem o site OD4B uma vez, antes que a criação real do site seja iniciada.

Trabalho de cronômetro remoto baseado em atualizações de perfil de usuário

Essa abordagem significa examinar os perfis de usuário para verificar para quem o site OD4B foi criado e, em seguida, aplicar as alterações aos sites conforme necessário. Isso significaria um trabalho agendado em execução fora do SharePoint, que periodicamente marcar o status e executará as personalizações necessárias. O trabalho agendado pode estar sendo executado como um WebJob no Azure ou tão simples quanto o script do PowerShell agendado em seu próprio agendador de janelas. Obviamente, a escala da implantação tem um enorme impacto na opção de agendamento escolhida.

1. É iniciada uma tarefa agendada que acessará perfis de usuário dos usuários para verificar quem tem o site OD4B provisionado
2. Os sites reais são personalizados um por um com base nos requisitos de negócios

Uma das principais desvantagens dessa opção é que claramente pode haver uma situação em que o usuário possa acessar os sites OD4B antes que as personalizações tenham sido aplicadas. Ao mesmo tempo, essa opção é interessante para outras opções para garantir que os usuários finais não tenham alterado nenhuma das configurações necessárias nos sites ou para marcar que o conteúdo do site OD4B esteja alinhado com as políticas da empresa.

Personalização baseada em parte de aplicativo aprimorada

Aqui está uma descrição mais detalhada das personalizações baseadas em parte de aplicativo aprimoradas, que parece ser a abordagem típica para aplicar e gerenciar personalizações necessárias aos sites OD4B. O código-fonte e detalhes adicionais sobre essa solução estão disponíveis nas diretrizes Office 365 Padrões e Práticas do Desenvolvedor.

O design lógico real segue a abordagem de parte do aplicativo oculto, mencionada antes nesta postagem no blog. Isso significa que a suposição é que você centralizou a Intranet no ambiente Office 365 em que você pode colocar a parte do aplicativo necessária e que os usuários finais estarão chegando a esta página de boas-vindas quando abrirem o navegador. É comum que cada navegador da empresa tenha o mesmo conjunto de home page usando políticas de grupo, para que os usuários finais sempre comecem de um local centralizado quando abrirem o navegador. Este é o local em que você colocaria a parte do aplicativo, que pode ser definida como tamanho como 0 pixel de largura e altura. O ponto chave aqui é que você usa o contexto do usuário final para executar a parte do aplicativo, que contém a página do suplemento hospedado pelo provedor.

Considerações sobre otimização de desempenho e manutenção

Como essa parte do aplicativo será executada sempre que o usuário chegar à primeira página da intranet, precisamos considerar o impacto de desempenho disso ou como fazer com que o código funcione com eficiência e apenas execute partes-chave das execuções de código quando realmente necessário. A segunda consideração de otimização também é onde colocamos ativos reais que são usados em cada um dos sites. Estes são desafios bastante típicos para enfrentar com quaisquer personalizações. Aqui está uma pequena lista de coisas para se concentrar em implementações de modelo de aplicativo.

• Local dos ativos – solução de CDN (rede de entrega de conteúdo centralizada), em cada coleção de sites ou na coleção de sites raiz?
• Taxa de atualização dos ativos ou como garantir que, independentemente do cache do navegador do lado do cliente, possamos garantir que executemos versões mais recentes dos scripts (JavaScript) ou mostre as versões mais recentes das imagens?
• Redução da execução do código para evitar carga desnecessária para o serviço do Azure e Office 365
• Personalizações de versão que são aplicadas ao site OD4B

Localização dos ativos

Há poucas soluções diferentes para isso. No exemplo de código de referência, usamos a inserção do JavaScript em cada um dos sites OD4B para fornecer a mensagem de política da empresa e remover a possibilidade de criar sub-sites (ou ocultar o link). Nesta solução específica, estamos carregando o arquivo JavaScript necessário para a coleção de sites raiz do esquema de endereços OneDrive for Business e referenciamos esse arquivo diretamente desse local nos sites OD4B individuais. Isso significa que você só tem um local para manter e atualizar o arquivo JavaScript, se alguma alteração for necessária.

Nesta implementação de referência, na verdade, também atualizamos esse arquivo sempre que o WebJob é executado, o que certamente não é necessário, mas o código de exemplo deveria estar funcionando tão facilmente sem nenhuma etapa adicional e possível. Da mesma forma, você pode carregar o arquivo JavaScript manualmente para a coleção de sites raiz e, em seguida, referenciar isso a partir daí. A solução alternativa também seria usar alguma CND para armazenar o arquivo necessário ou fazer referência ao JavaScript do lado do aplicativo hospedado do provedor. Desde que você tenha apenas uma cópia do arquivo, você terá:

Desafio de cache do lado do cliente e como resolver isso

Um dos desafios com a implementação baseada em JavaScript é o cache do lado do cliente. Quando os navegadores baixarem arquivos JavaScript usados, eles armazenarão em cache esses arquivos para reduzir a quantidade de ativos baixados para solicitações a seguir. Isso é ótimo na perspectiva de otimização de desempenho, mas causa um desafio quando precisamos atualizar o arquivo JavaScript. Na pior das hipóteses, o arquivo JavaScript armazenado em cache causará exceções com outras atualizações introduzidas com versões atualizadas.

Para remover esse problema, podemos começar a usar o atributo de revisão com referência de URL javaScript. Quando associamos a ação personalizada do usuário ao site OD4B, incluímos a URL do JavaScript para ter GUID exclusivo na URL. Aqui está o exemplo da referência que apontará para o site raiz da coleção de sites. Observe o GUID adicional que foi adicionado após o atributo rev na URL. Sempre que o personalizador for executado para determinado site OD4B, esse atributo será atualizado. Na prática, isso significa que o arquivo JavaScript é armazenado em cache no navegador até que haja uma nova versão adicionada ao site OD4B, que alterará a URL e, portanto, o navegador baixará a nova versão e armazenará em cache isso após a próxima atualização.

• /OneDriveCustomization/OneDriveConfiguration.js?rev=4bb89029e7ba470e893170d4cba7de000

Aqui está o código que é usado para gerar a URL JavaScript para a ação personalizada do usuário.

/// <summary>
/// Just to build the JS path which can be then pointed to the OneDrive site.
/// </summary>
/// <returns></returns>
public string BuildJavaScriptUrl(string siteUrl)
{
    // Solve root site collection URL
    Uri url = new Uri(siteUrl);
    string scenarioUrl = String.Format("{0}://{1}:{2}/{3}", 
                            url.Scheme, url.DnsSafeHost, 
                            url.Port, JSLocationFolderName);
    // Unique rev generated each time JS is added, so that we force browsers to 
    // refresh JS file wiht latest version
    string revision = Guid.NewGuid().ToString().Replace("-", "");
    return string.Format("{0}/{1}?rev={2}", scenarioUrl, JSFileName, revision);
}

Execução reduzida do código

Como esse processo se baseia em ter uma parte oculta do aplicativo na primeira página da Intranet, isso significará que o código será executado sempre que o usuário atualizar seu navegador ou se mudar para a página. Como essa primeira página geralmente é definida como a home page padrão do navegador para os usuários corporativos, o código seria executado sempre que uma sessão do navegador fosse iniciada.

No entanto, como não atualizamos as personalizações aplicadas aos sites OD4B com frequência, não adianta iniciar todo o processo de atualização de personalização em primeiro lugar. Ao fazer isso, reduzimos o uso das filas de armazenamento e da execução do trabalho web, o que reduzirá diretamente os custos associados ao lado do aplicativo hospedado do provedor, pois não usaremos tanta CPU e outros recursos em nosso design.

A maneira mais fácil de garantir que nosso processamento não seja executado em cada solicitação é usar a abordagem clássica de cookie do navegador, em que armazenaremos cookie específico para o navegador do cliente com tempo de vida específico. Ao verificar essa existência de cookie, podemos ignorar a execução até que o cookie tenha expirado e é quando marcar novamente o status de personalização real nos sites OD4B.

Aqui está o que temos no método de carregamento de página para a parte do aplicativo. Essa chamada de método marcar existência do cookie e, se o cookie existir, ignoraremos o código comercial real até que a execução seja novamente necessária.

// Check if we should skip this check. We do this only once per hour to avoid 
// perf issues and there's really no point even hitting the user profile 
// in every request.
if (CookieCheckSkip())
    return;

O cookie real status e a configuração do cookie são feitos da seguinte maneira.

/// <summary>
/// Checks if we need to execute the code customization code again. 
/// Timer set to 60 minutes to avoid constant execution of the code for nothing.
/// </summary>
/// <returns></returns>
private bool CookieCheckSkip()
{
    // Get cookie from the current request.
    HttpCookie cookie = Request.Cookies.Get("OneDriveCustomizerCheck");

    // Check if cookie exists in the current request.
    if (cookie == null)
    {
        // Create cookie.
        cookie = new HttpCookie("OneDriveCustomizerCheck");
        // Set value of cookie to current date time.
        cookie.Value = DateTime.Now.ToString();
        // Set cookie to expire in 60 minutes.
        cookie.Expires = DateTime.Now.AddMinutes(60);
        // Insert the cookie in the current HttpResponse.
        Response.Cookies.Add(cookie);
        // Output debugging information
        WriteDebugInformationIfNeeded(
            string.Format(@"Cookie did not exist, adding new cookie with {0} 
                            as expiration. Execute code.",
                            cookie.Expires));
        // Since cookie did not existed, let's execute the code, 
        // so skip is false.
        return false;
    }
    else
    {
        // Output debugging information
        WriteDebugInformationIfNeeded(string.Format(@"Cookie did existed, 
                                    with {0} as expiration. Skipping code.", 
                                    cookie.Expires));
        //  Since cookie did existed, let's skip the code
        return true;
    }
}

Se você tiver uma visão mais detalhada do código na página de parte do aplicativo, verá que em cada chamada fazemos marcar as existências do site OD4B para o usuário final. Como isso só pode ser feito acessando o perfil do usuário, o código terá impacto no desempenho. Usando o cookie acima marcar, podemos melhorar a experiência do usuário final e evitamos atingir o serviço de perfil de usuário constantemente sem requisitos reais. Também é bom notar que colocamos esse cookie marcar como a primeira etapa no método Page_Load, para que ignoremos todo o processamento, se necessário. Aqui está um pequeno snippet do método Page_Load do Customizer.aspx para mostrar o processo de código.

protected void Page_Load(object sender, EventArgs e)
{
    // Check if we should skip this check. We do this only once per hour to avoid 
    // perf issues and there's really no point even hitting the user profile 
    // in every request.
    if (CookieCheckSkip())
        return;
  
    var spContext = 
        SharePointContextProvider.Current.GetSharePointContext(Context);
    using (ClientContext clientContext = 
        spContext.CreateUserClientContextForSPHost())
    {
        // Get user profile
        ProfileLoader loader = ProfileLoader.GetProfileLoader(clientContext);
        UserProfile profile = loader.GetUserProfile();
        Microsoft.SharePoint.Client.Site personalSite = profile.PersonalSite;

        clientContext.Load(profile, prof => prof.AccountName);
        clientContext.Load(personalSite);
        clientContext.ExecuteQuery();

        // Let's check if the site already exists
        if (personalSite.ServerObjectIsNull.Value)
        {

Personalizações de versão que são aplicadas ao site OD4B

O segundo nível de otimização em nosso processamento de código é feito por meio da versão especificamente das personalizações que implantamos nos sites OD4B. O que isso significa é que armazenamos a versão das personalizações no saco de propriedades do site OD4B e apenas atualizamos os arquivos e ativos, se necessário. Isso significa que, na execução do WebJob, comparamos a versão de personalização atualmente no OD4B com a versão que estamos prestes a implantar e somente se a versão de personalização não existir no site OD4B, carregaremos os ativos necessários e aplicaremos outras configurações.

Essa abordagem também reduzirá significativamente os recursos necessários do Microsoft Azure, pois evitamos atualizar ou executar o código de personalização real quando ele não for necessário. Isso significa redução da CPU e de outros recursos no Microsoft Azure e menos solicitações para Office 365.

Toda a lógica de personalização é armazenada neste exemplo está localizada no método ApplySiteConfiguration no OD4B. Classe Configuration.Async.Common.SiteModificationManager . Esse método também é chamado pelo WebJob com parâmetros certos para iniciar o processo de personalização. Antes de realmente executar qualquer operação, estamos verificando o valor do pacote de propriedades com uma chave de 'Contoso_OneDriveVersion' e a execução só continuará se a versão atual no site for menor do que a versão que estamos planejando aplicar. Aqui está o código real que está usando o componente do Office PnP Core para simplificar o código.

// Check current site configuration status - is it already in right version?
if (ctx.Web.GetPropertyBagValueInt(
    SiteModificationManager.OneDriveMarkerBagID, 0) 
    < SiteModificationManager.BrandingVersion)
{

Quando a personalização for aplicada ao site, definiremos a versão de personalização aplicada no saco de propriedades para a execução a seguir.

// Save current branding applied indicator to site
ctx.Web.SetPropertyBagValue(SiteModificationManager.OneDriveMarkerBagID, SiteModificationManager.BrandingVersion);

Este é um processo relativamente simples, mas reduzirá significativamente os recursos necessários do Azure e também reduzirá as operações remotas unnecesasrey para Office 365, que terão impacto positivo no desempenho.

Configuração necessária no Azure

O principal requisito para que esse exemplo funcione corretamente é que você criou o Serviço de Dados de Armazenamento do Azure e atualizou as cadeias de conexão de armazenamento de acordo com os projetos, que os estão usando. Você pode simplesmente criar como serviço de armazenamento no portal de administração do Azure (manage.windowssazure.com), selecionando Novo –> Serviços de Dados –> Armazenamento –> Create Rápido. Depois disso, você só precisará definir nome, local e algumas outras configurações e você está pronto para ir.

Quando o armazenamento foi criado, você precisa ir e copiar a chave necessária para o cadeia de conexão. Ao migrar para a página de detalhes do armazenamento, você pode acessar informações importantes clicando em "Gerenciar Chaves de Acesso" na parte inferior da página.

Você precisará atualizar App.config arquivo para os seguintes projetos na solução do Visual Studio. Cada um dos projetos é explicado mais adiante nesta postagem no blog.

OD4B. Configuration.Async.WebJob OD4B. O projeto Configuration.Async.Console.SendMessage WebJob tem duas chaves, que podem ser atualizadas para apontar para a mesma conexão e o SendMessage tem apenas uma chave para atualizar.

Estrutura de solução de referência

Essa solução do Visual Studio consiste em algumas soluções, mas cada uma delas tem motivos bastante razoáveis para estar lá. Aqui está a introdução a cada um dos projetos na solução e por que eles existem ou para que eles são.

OD4B.Configuration.Async

Este é o projeto de aplicativo real do SharePoint, que apresentará o aplicativo hospedado do provedor ao SharePoint e solicitará as permissões necessárias. Observe que, embora não executemos operações de nível de locatário na parte do aplicativo, estamos solicitando permissões muito altas para o suplemento. Isso ocorre porque usaremos a mesma ID do cliente e o segredo deste arquivo de aplicativo em nossa execução do WebJob. Usando essa abordagem, você não precisa registrar manualmente a ID do aplicativo e o segredo no SharePoint, preferimos usar apenas a mesma solução cruzada de identificador e segredo.

Este projeto também contém a definição de parte do aplicativo que será implantada na Web do host.

OD4B. Configuration.Async.Common

Este projeto contém toda a lógica de negócios real e projetos cruzados de código compartilhado, como a definição para o objeto de dados que é colocado na fila de armazenamento e a lógica de negócios real para personalizar sites OD4B. O motivo para colocar o código aqui é simplesmente para nos dar uma maneira mais fácil de desenvolver e testar as operações quando o projeto é criado. Assim como no desenvolvimento geral, você não deve realmente colocar seu código lógico de negócios diretamente no WebJob ou na parte do aplicativo, em vez de localizar isso na camada lógica de negócios para facilitar o teste e a reutilização de código.

Todas as operações reais para os sites OD4B estão localizadas no OD4B. Classe Configuration.Async.Common.SiteModificationManager .

OD4B. Configuration.Async.Console.Reset

Este projeto é nosso projeto de teste e depuração para as personalizações reais. Ele pode ser usado para aplicar manualmente as personalizações desejadas a qualquer site OD4B. Durante o tempo de desenvolvimento, este projeto foi nosso projeto de teste para testar o processo de personalização antes de ser conectado ao WebJob. O projeto também pode ser usado para redefinir personalizações de qualquer site OD4B para fins de demonstração ou teste. Como a lógica comercial real está localizada no projeto comum, esse projeto usará a mesma classe SiteModificationManager que as outras para aplicar ou redefinir personalizações dos sites.

Ao testar as personalizações, você pode simplesmente alterar o código no método Principal entre Aplicar e Redefinir para alterar a operação desejada.

static void Main(string[] args)
{
  
    Uri url = 
        new Uri("https://vesaj-my.sharepoint.com/personal/vesaj_veskuonline_com");
  
        //get the new site collection
    string realm = TokenHelper.GetRealmFromTargetUrl(url);
    var token = TokenHelper.GetAppOnlyAccessToken(
                    TokenHelper.SharePointPrincipal, 
                    url.Authority, realm).AccessToken;
    using (var ctx = 
        TokenHelper.GetClientContextWithAccessToken(url.ToString(), 
        token))
    {
        // Uncomment the one you need for testing/reset
        // Apply(ctx, url);
        Reset(ctx);
    }
}

Observe que você precisará garantir que a ID do aplicativo e o segredo deste projeto no app.config estejam correspondendo aos que você deu permissões necessárias ao seu locatário. Você pode executar facilmente o projeto clicando com o botão direito do mouse no projeto e escolhendo Depurar – Iniciar Nova Instância, para que você possa andar o código real que é executado linha por linha.

OD4B. Configuration.Async.Console.SendMessage

Este projeto foi adicionado à solução para testar o mecanismo de fila de armazenamento antes de ser conectado à parte do aplicativo. O projeto pode ser usado passando o processo de parte do aplicativo para adicionar novas mensagens à fila de armazenamento. Observe que você precisará atualizar a fila de armazenamento cadeia de conexão de acordo no app.config para fazer o projeto funcionar corretamente.

Você pode executar facilmente o projeto clicando com o botão direito do mouse no projeto e escolhendo Depurar – Iniciar Nova Instância, para que você possa andar o código real que é executado linha por linha.

OD4B. Configuration.Async.WebJob

Este é o projeto WebJob real, que foi criado usando o modelo de projeto WebJob, introduzido no Visual Studio 2013 Update 4. Este modelo facilita a criação de projetos do WebJob adicionando referências corretas no local e também fornece boa automação de implantação com suporte ao clique com o botão direito do mouse para o projeto. Você pode simplesmente implantar a versão inicial ou nova versão do projeto no Azure clicando com o botão direito do mouse e selecionando Publicar como Trabalho Web do Azure... que abrirá o assistente de publicação.

Esse WebJob é criado como um WebJob contínuo, que é necessário para o processamento baseado em fila. Isso significa que, no método Main, apenas definimos o processo para executar continuamente como segue.

class Program
{
    // Please set the following connection strings in app.config for this 
    // WebJob to run: AzureWebJobsDashboard and AzureWebJobsStorage
    static void Main()
    {
        var host = new JobHost();
        // The following code ensures that the WebJob will be 
        // running continuously
        host.RunAndBlock();
    }
}

O processamento de fila real é muito fácil com o WebJobs. A única coisa que precisamos fazer é definir os atributos certos para o método e garantir que as cadeias de conexão de armazenamento do Azure na configuração do aplicativo sejam atualizadas de acordo e que correspondam aos da fila de armazenamento que você criou com o Microsoft Azure. A seguir está o método ProcessQueueMessage da classe functions.cs. Observe como usamos o modelo de token Somente aplicativo para acessar o SharePoint do WebJob. Para que isso funcione, você precisará garantir que tenha copiado a ID do aplicativo e o segredo corretos para o app.config do projeto. A lógica de negócios real está localizada na classe SiteModificationManager , portanto, chamamos isso apenas com o contexto e parâmetros de cliente certos.

// This function will get triggered/executed when a new message is written 
// on an Azure Queue called queue.
public static void ProcessQueueMessage(
    [QueueTrigger(SiteModificationManager.StorageQueueName)] 
    SiteModificationData request, TextWriter log)
{
    Uri url = new Uri(request.SiteUrl);
  
    //Connect to the OD4B site sing App Only access
    string realm = TokenHelper.GetRealmFromTargetUrl(url);
    var token = TokenHelper.GetAppOnlyAccessToken(
        TokenHelper.SharePointPrincipal, url.Authority, realm).AccessToken;

    using (var ctx = TokenHelper.GetClientContextWithAccessToken(
        url.ToString(), token))
    {
        // Set configuration object properly for setting the config
        SiteModificationConfig config = new SiteModificationConfig()
        {
            SiteUrl = url.ToString(),
            JSFile = Path.Combine(Environment.GetEnvironmentVariable
                ("WEBROOT_PATH"), "Resources\\OneDriveConfiguration.js"),
            ThemeName = "Garage",
            ThemeColorFile = Path.Combine(Environment.GetEnvironmentVariable
                ("WEBROOT_PATH"), "Resources\\Themes\\Garage\\garagewhite.spcolor"),
            ThemeBGFile = Path.Combine(Environment.GetEnvironmentVariable
                ("WEBROOT_PATH"), "Resources\\Themes\\Garage\\garagebg.jpg"),
            ThemeFontFile = "" // Ignored in this case, but could be also obviously set
        };

        new SiteModificationManager().ApplySiteConfiguration(ctx, config);
    }
}

Outra coisa que vale a pena observar é que você precisará garantir que você tenha definido a propriedade Copy Local para a propriedade de referências de assembly do CSOM do SharePoint para o projeto, para que todos os assemblies dependentes sejam copiados corretamente para o Azure quando você implantar o trabalho Web. Isso ocorre simplesmente porque esses assemblies não estão localizados no site normal do Azure por padrão, portanto, definindo essa propriedade True, você garantirá que os assemblies referenciados também sejam copiados para nuvem.

OD4B. Configuration.AsyncWeb

Este é o aplicativo hospedado do provedor real que está hospedado no Microsoft Azure. Ele contém a página da parte do aplicativo, que é colocada na primeira página da intranet. Default.aspx página deste aplicativo não contém nenhuma operação, ela mostra detalhes sobre como usar o aplicativo.

Aviso. Se você enfrentar problemas de permissão negados com o acesso somente ao WebJob ou aplicativo em geral, verifique se você atualizou a ID do cliente do aplicativo e o segredo no app.config para corresponder aos valores no web.config deste projeto. O Visual Studio pode alterar esses valores em determinados cenários.

Processamento de filas no WebJob

O uso das filas de armazenamento é realmente direto com as APIs disponíveis no Azure. A maneira mais fácil de começar é usar o pacote Nuget 'Armazenamento do Windows Azure', que associará todas as APIs necessárias e outros pacotes ao seu projeto. Depois de adicionar esse pacote Nuget, você pode simplesmente começar a usar as APIs de fila de armazenamento para o processamento. A seguir está snippet do OD4B. Projeto Configuration.Async.Common (método AddConfigRequestToQueue na classe SiteModificationManager), que contém o código real de tratamento de mensagens de fila e é usado de vários projetos (desde a depuração de tempo de desenvolvimento mais fácil).

public void AddConfigRequestToQueue(
            string account, string siteUrl, string storageConnectionString)
{
    CloudStorageAccount storageAccount = 
                        CloudStorageAccount.Parse(storageConnectionString);
  
    // Get queue... create if does not exist.
    CloudQueueClient queueClient = storageAccount.CreateCloudQueueClient();
    CloudQueue queue = 
        queueClient.GetQueueReference(SiteModificationManager.StorageQueueName);
    queue.CreateIfNotExists();

    // Pass in data for modification
    var newSiteConfigRequest = new SiteModificationData()
    {
        AccountId = account,
        SiteUrl = siteUrl
    };

    // Add entry to queue
    queue.AddMessage(
        new CloudQueueMessage(
            JsonConvert.SerializeObject(newSiteConfigRequest)));
}

O processamento real da fila nesse caso foi feito com o projeto WebJob. No caso do WebJob, podemos simplesmente usar atributos específicos para automatizar o tratamento da fila. A única coisa que precisamos ter certeza é que estamos usando o mesmo cadeia de conexão de armazenamento e o nome da fila na parte de envio e recebimento.

// This function will get triggered/executed when a new message is written 
// on an Azure Queue called queue.
public static void ProcessQueueMessage(
    [QueueTrigger(SiteModificationManager.StorageQueueName)] 
    SiteModificationData request, TextWriter log)
{
    Uri url = new Uri(request.SiteUrl);

Não fica mais fácil do que isso. Observe que usamos SiteModificationManager.StorageQueueName em ambos os lados para garantir que o nome da fila esteja correspondendo.

Aplicar configurações reais ao site

Nestas implementações de referência, estamos executando as personalizações a seguir para cada um dos sites OD4B.

• Adicionar mensagem de política da empresa que é mostrada o tempo todo nos sites OD4B
• Ocultar a opção criar link do sub site na página de conteúdo do site
• Aplicar o tema personalizado ao site OD4B para corresponder à identidade visual da empresa

A política da empresa e ocultar o link criar sub-site estão sendo alcançados usando o chamado padrão de inserção JavaScript em que adicionamos ação personalizada do usuário ao nível do site com referência a um arquivo JavaScript específico, que está sendo executado em cada solicitação de página. Isso significa que podemos controlar o processamento de página usando tecnologias do lado do cliente adicionando, removendo ou atualizando qualquer elemento em qualquer página. Usando essa abordagem, não precisamos introduzir uma página de master personalizada, o que pode nos causar custos de manutenção de longo prazo mais significativos, especialmente se as alterações necessárias forem bastante mínimas.

A segunda operação com os temas personalizados exige que carreguemos alguns arquivos adicionais no site e, em seguida, defina-os para serem usados como configurações de tema. Usamos estritamente o CSOM para carregar todos os arquivos necessários nos sites para evitar complicações futuras com associações de elementos da estrutura de recursos. Como carregar um arquivo no SharePoint usando o CSOM é realmente simples, essa é definitivamente a maneira mais fácil de executar a automação e você não precisa se preocupar com nenhuma dependência de configurações específicas xml para soluções sandbox. Aqui está o método de configuração de site real do OD4B. Classe Configuration.Async.Common.SiteModificationManager. Observe que usamos o componente de núcleo PnP do desenvolvedor Office 365 para simplificar algumas das operações necessárias.

Também é bom notar que, de fato, carregamos uma nova versão do JS para a coleção de sites raiz sempre que personalizamos o site OD4B pessoal. Essa definitivamente não é uma solução ideal, ela está lá para fins de simplicidade para essa solução de referência. Você pode considerar adicionar essa operação de carregamento de arquivo JavaScript ao evento instalado do aplicativo, de modo que ele só seja feito uma vez quando o aplicativo estiver instalado, mas nesse caso você teria que fazer algum trabalho adicional com quaisquer atualizações nesse arquivo JS.

// This function will get triggered/executed when a new message is written 
// on an Azure Queue called queue.
public static void ProcessQueueMessage(
    [QueueTrigger(SiteModificationManager.StorageQueueName)] 
    SiteModificationData request, TextWriter log)
{
    Uri url = new Uri(request.SiteUrl);
  
    //Connect to the OD4B site using App Only token
    string realm = TokenHelper.GetRealmFromTargetUrl(url);
    var token = TokenHelper.GetAppOnlyAccessToken(
        TokenHelper.SharePointPrincipal, url.Authority, realm).AccessToken;

    using (var ctx = TokenHelper.GetClientContextWithAccessToken(
        url.ToString(), token))
    {
        // Set configuration object properly for setting the config
        SiteModificationConfig config = new SiteModificationConfig()
        {
            SiteUrl = url.ToString(),
            JSFile = Path.Combine(Environment.GetEnvironmentVariable
                ("WEBROOT_PATH"), "Resources\\OneDriveConfiguration.js"),
            ThemeName = "Garage",
            ThemeColorFile = 
                Path.Combine(Environment.GetEnvironmentVariable
                ("WEBROOT_PATH"), "Resources\\Themes\\Garage\\garagewhite.spcolor"),
            ThemeBGFile = 
                Path.Combine(Environment.GetEnvironmentVariable
                ("WEBROOT_PATH"), "Resources\\Themes\\Garage\\garagebg.jpg"),
            ThemeFontFile = "" // Ignored in this case, but could be also set
        };

        new SiteModificationManager().ApplySiteConfiguration(ctx, config);
    }
}

Obviamente, as operações necessárias são altamente dependentes de seus requisitos comerciais. Você pode encontrar vários padrões e abordagens diferentes com operações baseadas em CSOM do Office 365 Padrões e Práticas do Desenvolvedor.

Notas adicionais sobre soluções baseadas em WebJob

Aqui estão algumas anotações adicionais relacionadas ao desenvolvimento do WebJob no Azure. Esta é uma técnica extremamente poderosa que será definitivamente usada amplamente entre Office 365 personalizações. Você certamente verá soluções novas e aprimoradas com base na tecnologia WebJob serem adicionadas ao programa Office 365 Padrões de Desenvolvedores & Practices também.

Depuração do WebJob e do processo de personalização

Uma das boas práticas para o código em geral é localizar as operações reais fora do processo de execução final real, para que você possa primeiro se concentrar em testar o código necessário facilmente simplesmente usando o aplicativo de console ou, por exemplo, com projetos de teste no Visual Studio. Dessa forma, você pode garantir que a lógica de negócios real seja totalmente funcionalidade antes de conectá-la ao processo final, nesse caso, significando o WebJob. Neste caso de solução de referência, colocamos todo o código de negócios no OD4B. Classe Configuration.Async.Common.SiteModificationManager e chamamos isso de vários locais.

Isso significava que, durante o tempo de desenvolvimento, poderíamos usar o OD4B. Aplicativo de console Configuration.Async.Console.Reset para testar e redefinir as personalizações quantas vezes for necessário dos sites para garantir que a lógica de negócios seja totalmente sólida. Isso realmente não tem nada a ver com o modelo de suplemento do SharePoint ou o desenvolvimento do Azure, práticas de desenvolvimento passo a passo bastante práticas, independentemente da tecnologia que você usa. Durante os tempos em que eu era palestrante no treinamento de certificação mcm para SharePoint eu estava me referindo a isso como o método NKOTB, mas isso não é realmente uma terminologia padrão do setor :-)

Uma das grandes melhorias da perspectiva de depuração para o WebJobs foi introduzida no Visual Studio 2014 Update 4. Com as conexões e modelos de projeto do Azure recém-introduzidos, você pode realmente fazer depuração remota com o WebJob em execução no lado do Azure. Você precisará implantar o WebJob no Azure e, depois disso, poderá iniciar a sessão de depuração clicando com o botão direito do mouse na instância do WebJob no servidor Explorer e escolher Anexar Depurador no menu de contexto.

Há até um testador para enviar mensagens formatadas com razão para a fila na solução de referência. OD4B. O projeto Configuration.Async.Console.SendMessage foi criado simplesmente para ter a oportunidade de depurar o processo WebJob sem ser forçado a implantar a parte do aplicativo em qualquer lugar. Isso voltou novamente na depuração e no teste de todo o processo passo a passo.

Variáveis de ambiente WebJob

Uma das coisas interessantes sobre os WebJobs é que eles estão em execução em sites do Azure, mas seu local de execução é ligeiramente diferente dos sites normais no Azure. O que quero dizer com isso é que, se você implantar arquivos ou ativos adicionais junto com o WebJob no Azure, poderá enfrentar desafios se assumir que pode referenciar esses ativos diretamente usando caminhos relativos clássicos no código WebJob.

Nesse caso, tínhamos um arquivo JavaScript e poucos arquivos para o tema personalizado, que foram implantados no site do Azure, para que eles pudessem ser carregados nos sites do SharePoint conforme necessário. Você pode ver esses arquivos no Azure se estender o branch Arquivos em um site específico.

Normalmente, em sites do Azure, você pode fazer referência a esses arquivos usando o formato a seguir

string path = HostingEnvironment.MapPath(
    string.Format("~/{0}", "Resources/OneDriveConfiguration.js"));

Como o WebJobs, no entanto, é executado em local diferente e não no contexto do IIS, a referência acima ao arquivo não funcionaria, pois o mapeamento falharia no contexto do processo WebJob. É aqui que variáveis de ambiente específicas do WebJob podem ajudar. No caso da solução de referência, usamos a variável de ambiente específica do WebJob WEBROOT_PATH para obter acesso na pasta de site associada.

string jsFile = Path.Combine(
    Environment.GetEnvironmentVariable("WEBROOT_PATH"), 
    "Resources\\OneDriveConfiguration.js");

Há também algumas outras variáveis de ambiente para WebJobs, o que pode ajudá-lo. Você pode marcar as diferentes variáveis de ambiente usando código e há boas referências no GitHub para isso.

Vídeo demonstrando a solução e as ações

Aqui está um vídeo mostrando a solução na prática, incluindo a explicação das estruturas de solução e como você a usaria em seu ambiente Office 365 para modificar OneDrive for Business sites.

Links relacionados

• Personalizar os sites do OneDrive for Business
• Artigos de diretrizes em https://aka.ms/OfficeDevPnPGuidance
• Referências no MSDN em https://aka.ms/OfficeDevPnPMSDN
• Vídeos em https://aka.ms/OfficeDevPnPVideos

Exemplos de PnP

• OD4B. Configuration.Async (Exemplo de PnP O365)
• Provisionamento.OneDriveProvisioning (Exemplo de PnP O365)
• Componente do Office PnP Core
• Exemplos e conteúdo no Microsoft 365 Patterns and Practices (PnP)

Aplicável a

• Office 365 Multilocatário (MT)
• Office 365 dedicado (D) parcialmente
• SharePoint 2013 local, parcialmente

Os padrões para dedicados e locais são idênticos às técnicas de modelo do suplemento do SharePoint, mas há diferenças nas possíveis tecnologias que podem ser usadas.