Tutorial: compartilhar código entre um Suplemento VSTO e um Suplemento do Office com uma biblioteca de códigos compartilhados

  • Artigo

Os suplementos do Visual Studio Tools for Office (VSTO) são ótimos para a ampliação do Office para fornecer soluções para seus negócios ou para outras pessoas. Eles já estão por aqui há muito tempo e há milhares de soluções criadas com o VSTO. No entanto, eles só são executados no Office no Windows. Não pode executar Suplementos VSTO no Mac, na Web ou em plataformas móveis.

Importante

Os suplementos COM e VSTO não são suportados no novo Outlook no Windows que está atualmente em pré-visualização. Estes suplementos ainda são suportados no cliente de ambiente de trabalho clássico do Outlook no Windows. Para saber mais, consulte Desenvolver suplementos do Outlook para o novo Outlook no Windows.

Os suplementos do Office usam HTML, JavaScript e tecnologias da Web adicionais para criar soluções do Office em todas as plataformas. Migrar seu Suplemento VSTO existente para um Suplemento do Office é uma ótima maneira de disponibilizá-lo em todas as plataformas.

Talvez você queira manter o Suplemento VSTO e um novo Suplemento do Office que tenham a mesma funcionalidade. Isso permite que você continue servindo aos clientes que usam o suplemento VSTO no Office no Windows. Isso também permite fornecer a mesma funcionalidade em um Suplemento do Office para clientes em todas as plataformas. Você também pode Tornar seu Suplemento do Office compatível com o Suplemento VSTO existente.

No entanto, é melhor evitar reescrever todo o código do seu Suplemento VSTO para o Suplemento do Office. Este tutorial mostra como evitar a reconfiguração de código usando uma biblioteca compartilhadas de códigos para ambos os suplementos.

Biblioteca de códigos compartilhados

Este tutorial explica-lhe os passos para identificar e partilhar código comum entre o suplemento VSTO e um Suplemento do Office moderno. Utiliza um exemplo de Suplemento VSTO muito simples para os passos para que possa concentrar-se nas competências e técnicas de que precisa para trabalhar com os seus próprios Suplementos VSTO.

O diagrama a seguir mostra como a biblioteca de códigos compartilhada funciona para migração. O código comum é refatorado em uma nova biblioteca de códigos compartilhadas. O código pode permanecer escrito em seu idioma original, como o C# ou o VB. Isso significa que você pode continuar usando o código do suplemento VSTO existente, criando uma referência do projeto. Ao criar o Suplemento do Office, ele também usará a biblioteca de códigos compartilhados chamando-a através de APIs REST.

Diagrama de Suplemento VSTO e Suplemento do Office usando uma biblioteca de código compartilhada.

Habilidades e técnicas neste tutorial:

  • Criar uma biblioteca de classe compartilhada, refatorando o código em uma biblioteca de classe do .NET.
  • Crie um invólucro da API REST usando ASP.NET Core para a biblioteca de classe compartilhada.
  • Chame a API REST do Suplemento do Office para acessar o código compartilhado.

Pré-requisitos

Para configurar seu ambiente de desenvolvimento:

  1. Instalar o Visual Studio 2019.
  2. Instale as cargas de trabalho a seguir.
    • ASP.NET e desenvolvimento na Web
    • Desenvolvimento em várias plataformas do .NET Core
    • Desenvolvimento do Office/SharePoint
    • Os seguintes componentesindividuais.
      • Visual Studio Tools for Office (VSTO)
      • Runtime do .NET Core 3.0

Também são necessários:

O suplemento VSTO do analisador de células

Este tutorial usa a solução PnP Biblioteca compartilhada do Suplemento VSTO para o Suplemento do Office. A pasta /start contém a solução de Suplemento VSTO que irá migrar. Sua meta é migrar o Suplemento VSTO para um Suplemento do Office moderno, quando possível.

Observação

O exemplo utiliza C#, mas pode aplicar as técnicas neste tutorial a um Suplemento VSTO escrito em qualquer linguagem .NET.

  1. Baixe a solução PnP Biblioteca compartilhada do Suplemento VSTO para o Suplemento do Office para trabalhar em um arquivo em seu computador.
  2. Inicie o Visual Studio 2019 e abra a solução /start/Cell-Analyzer.sln.
  3. No menu Depurar, selecione Iniciar Depuração.

O suplemento é um painel de tarefas personalizado do Excel. Você pode selecionar qualquer célula com o texto e escolher o botão Mostrar o Unicode. Na seção Resultado, o suplemento exibirá uma lista de cada caractere no texto junto com seu número Unicode correspondente.

O suplemento VSTO do Analisador de Células em execução no Excel com o botão

Análise de tipos de código no suplemento VSTO

A primeira técnica a ser aplicada é analisar o suplemento para quais partes do código podem ser compartilhadas. Em geral, o Project é dividido em três tipos de códigos.

Código IU

O código da IU interage com o usuário. O código da interface de usuário do VSTO funciona com formulários do Windows. Os suplementos do Office usam HTML, CSS e JavaScript para IU. Devido a estas diferenças, não pode partilhar código de IU com o Suplemento do Office. A IU deve ser recriada em JavaScript.

Código do documento

No VSTO, o código interage com o documento através de objetos .NET, como Microsoft.Office.Interop.Excel.Range. No entanto, os Suplementos do Office utilizam a biblioteca Office.js. Embora sejam semelhantes, não são exatamente iguais. Por isso, mais uma vez, não pode partilhar o código de interação do documento com o Suplemento do Office.

Código lógico

A lógica empresarial, algoritmos, funções auxiliares e um código semelhante geralmente formam o coração de um suplemento VSTO. Esse código funciona independentemente da interface de usuário e do código do documento para executar a análise, conectar-se a serviços de backend, executar cálculos e muito mais. Esse é o código que pode ser compartilhado para que você não precise escrevê-lo novamente em JavaScript.

Vamos examinar o suplemento VSTO. No código a seguir, cada seção é identificada como um código de documento, IU ou de algoritmo.

// *** UI CODE ***
private void btnUnicode_Click(object sender, EventArgs e)
{
    // *** DOCUMENT CODE ***
    Microsoft.Office.Interop.Excel.Range rangeCell;
    rangeCell = Globals.ThisAddIn.Application.ActiveCell;

    string cellValue = "";

    if (null != rangeCell.Value)
    {
        cellValue = rangeCell.Value.ToString();
    }

    // *** ALGORITHM CODE ***
    //convert string to Unicode listing
    string result = "";
    foreach (char c in cellValue)
    {
        int unicode = c;

        result += $"{c}: {unicode}\r\n";
    }

    // *** UI CODE ***
    //Output the result
    txtResult.Text = result;
}

Com esta abordagem, pode ver que uma secção de código pode ser partilhada com o Suplemento do Office. O código seguinte tem de ser refatorizada numa biblioteca de classes separada.

// *** ALGORITHM CODE ***
//convert string to Unicode listing
string result = "";
foreach (char c in cellValue)
{
    int unicode = c;

    result += $"{c}: {unicode}\r\n";
}

Criar uma biblioteca de classe compartilhada

Os suplementos do VSTO são criados no Visual Studio como projetos .NET, portanto, reutilizaremos o .NET o máximo possível para simplificar. Nossa próxima técnica é criar uma biblioteca de classe e um código compartilhado de refatoração nessa biblioteca de classe.

  1. Caso ainda não o tenha feito, inicie o Visual Studio 2019 e abra a solução \start\Cell-Analyzer.sln.

  2. Clique com o botão direito do rato (ou selecione sem soltar) a solução no Explorador de Soluções e selecione Adicionar > Novo Projeto.

  3. Na caixa de diálogo Adicionar um novo projeto, escolha Biblioteca de Classe (.NET Framework)e escolha Próximo.

    Observação

    Não utilize a biblioteca de classes .NET Core porque não funcionará com o projeto VSTO.

  4. Na caixa de diálogo Configure seu novo Project, defina os seguintes campos.

    • Defina o Nome do projeto como CellAnalyzerSharedLibrary.
    • Deixe a Localização no valor predefinido.
    • Defina a estrutura como 4.7.2.

  5. Escolha Criar.

  6. Depois de criar o projeto, renomeie o arquivo Class1.cs para CellOperations.cs. Será exibida uma solicitação para renomear a classe. Renomeie o nome da classe para que ele corresponda ao nome do arquivo.

  7. Adicione o seguinte código à classe CellOperations para criar um método chamado GetUnicodeFromText.

    public class CellOperations
{
    static public string GetUnicodeFromText(string value)
    {
        string result = "";
        foreach (char c in value)
        {
            int unicode = c;

            result += $"{c}: {unicode}\r\n";
        }
        return result;
    }
}

Use a biblioteca de classe compartilhada no suplemento VSTO

Agora, você precisa atualizar o suplemento VSTO para usar a biblioteca de classe. É importante que o Suplemento VSTO e o Suplemento do Office usem a mesma biblioteca de classes compartilhadas para que correções de bugs ou recursos futuros sejam feitos em um único local.

  1. No Explorador de Soluções, clique com o botão direito do rato (ou selecione sem soltar) no projeto Cell-Analyzer e selecione Adicionar Referência.

  2. Selecione CellAnalyzerSharedLibrarye escolha OK.

  3. No Explorador de Soluções, expanda o projeto Cell-Analyzer , clique com o botão direito do rato (ou selecione sem soltar) no ficheiro de CellAnalyzerPane.cs e selecione Ver Código.

  4. No método btnUnicode_Click, exclua as linhas de código a seguir.

    //Convert to Unicode listing
string result = "";
foreach (char c in cellValue)
{
  int unicode = c;
  result += $"{c}: {unicode}\r\n";
}

  5. Atualize a linha de código sob o comentário //Output the result para ler da seguinte maneira:

    //Output the result
txtResult.Text = CellAnalyzerSharedLibrary.CellOperations.GetUnicodeFromText(cellValue);

  6. No menu Depurar, selecione Iniciar Depuração. O painel de tarefas personalizado deve funcionar conforme o esperado. Digite um texto em uma célula e, em seguida, teste para convertê-lo em uma lista Unicode com o suplemento.

Criar um invólucro da API REST

O suplemento VSTO pode usar a biblioteca de classes compartilhadas diretamente, uma vez que ambos são projetos .NET. No entanto, o Suplemento do Office não poderá usar o .NET, uma vez que ele usa o JavaScript. Em seguida, irá criar um wrapper da API REST. Isso permite que o Suplemento do Office chame uma API REST, que passa a chamada para a biblioteca de classes compartilhadas.

  1. No Explorador de Soluções, clique com o botão direito do rato (ou selecione sem soltar) no projeto Cell-Analyzer e selecione Adicionar > Novo Projeto.

  2. Em Adicionar uma nova caixa de diálogo do projeto, escolha Aplicativo Web ASP.NET Core e escolha Próximo.

  3. Na caixa de diálogo Configure seu novo Project, defina os seguintes campos.

    • Defina o nome do projeto para CellAnalyzerRESTAPI.
    • No campo Local, deixe o valor padrão.

  4. Escolha Criar.

  5. Na caixa de diálogo criar um novo aplicativo Web ASP.NET Core, selecione ASP.NET Core 3.1 da versão e selecione API na lista de projetos.

  6. Deixe todos os outros campos em valores padrão e escolha o botão Criar.

  7. Depois de criar o projeto, expanda o projetoCellAnalyzerRESTAPI no Gerenciador de soluções.

  8. Clique com o botão direito do rato (ou selecione sem soltar) Dependências e selecione Adicionar Referência.

  9. Selecione CellAnalyzerSharedLibrarye escolha OK.

  10. Clique com o botão direito do rato (ou selecione sem soltar) na pasta Controladores e selecione Adicionar > Controlador.

  11. Na caixa de diálogo Adicionar Novo Item Estruturado , selecione Controlador de API – Vazio e, em seguida, selecione Adicionar.

  12. Na caixa de diálogo Adicionar Controlador de API Vazio , dê ao controlador o nome AnalyzeUnicodeController e, em seguida, selecione Adicionar.

  13. Abra o arquivo AnalyzeUnicodeController.cs e adicione o código a seguir como um método para a classe AnalyzeUnicodeController.

    [HttpGet]
public ActionResult<string> AnalyzeUnicode(string value)
{
  if (value == null)
  {
    return BadRequest();
  }
  return CellAnalyzerSharedLibrary.CellOperations.GetUnicodeFromText(value);
}

  14. Clique com o botão direito do rato (ou selecione sem soltar) no projeto CellAnalyzerRESTAPI e selecione Definir como Projeto de Arranque.

  15. No menu Depurar, selecione Iniciar Depuração.

  16. Um navegador será iniciado. Insira a seguinte URL para testar se a API REST está funcionando: https://localhost:<ssl port number>/api/analyzeunicode?value=test. Você pode reutilizar o número da porta na URL no navegador que o Visual Studio iniciou. Você deverá ver uma cadeia de caracteres retornada com valores Unicode para cada caractere.

Criar o Suplemento do Office

Ao criar o Suplemento do Office, ele faz uma chamada para a API REST. Mas, primeiro, você precisa obter o número da porta do servidor da API REST e salvá-lo para mais tarde.

Salve o número da porta SSL

  1. Caso ainda não o tenha feito, inicie o Visual Studio 2019 e abra a solução \start\Cell-Analyzer.sln.
  2. No projeto CellAnalyzerRESTAPI, expanda Propriedadese abra o arquivo launchSettings. JSON.
  3. Localize a linha de código com o valor sslPort, copie o número da porta e salve-o em algum lugar.

Adicione o projeto do Suplemento do Office

Para simplificar, mantenha todo o código em uma solução. Adicione o projeto do Suplemento do Office à solução existente do Visual Studio. No entanto, se estiver familiarizado com o gerador Yeoman para Suplementos do Office e o Visual Studio Code, também pode executar para criar yo office o projeto. As etapas são muito semelhantes.

  1. No Explorador de Soluções, clique com o botão direito do rato (ou selecione sem soltar) a solução Analisador de Células e selecione Adicionar > Novo Projeto.
  2. Nacaixa de diálogo Adicionar um novo projeto, clique em Suplemento do Web Add-ine escolha Próximo.
  3. Na caixa de diálogo Configure seu novo Project, defina os seguintes campos.
    • Defina o nome do projeto comoCellAnalyzerOfficeAddin.
    • Deixe a Localização no valor predefinido.
    • Defina a estrutura como 4.7.2ou superior.
  4. Escolha Criar.
  5. Na caixa de diálogoEscolha o tipo de suplemento, selecione Adicionar novas funcionalidades ao Excele escolha Concluir.

Dois projetos serão criados:

  • CellAnalyzerOfficeAddin - este projeto configura os arquivos XML de manifesto que descrevem o suplemento, para que o Office possa carregá-lo corretamente. Ele contém o ID, nome, descrição e outras informações sobre o suplemento.
  • CellAnalyzerOfficeAddinWeb - este projeto contém recursos da Web para seu suplemento, como HTML, CSS e scripts. Ele também configura uma instância do IIS Express para hospedar seu suplemento como um aplicativo Web.

Adicionar interface de usuário e funcionalidade ao Suplemento do Office

  1. No Gerenciador de soluções, expanda o projetoCellAnalyzerOfficeAddinWeb.

  2. Abra o arquivo Home.HTML e substitua o conteúdo de <body> pela seguinte HTML.

    <button id="btnShowUnicode" onclick="showUnicode()">Show Unicode</button>
<p>Result:</p>
<div id="txtResult"></div>

  3. Abra o arquivo Home.js e substitua todo o conteúdo pelo seguinte código.

    (function () {
  "use strict";
  // The initialize function must be run each time a new page is loaded.
  Office.initialize = function (reason) {
    $(document).ready(function () {
    });
  };
})();

function showUnicode() {
  Excel.run(function (context) {
    const range = context.workbook.getSelectedRange();
    range.load("values");
    return context.sync(range).then(function (range) {
      const url = "https://localhost:<ssl port number>/api/analyzeunicode?value=" + range.values[0][0];
      $.ajax({
        type: "GET",
        url: url,
        success: function (data) {
          let htmlData = data.replace(/\r\n/g, '<br>');
          $("#txtResult").html(htmlData);
        },
        error: function (data) {
            $("#txtResult").html("error occurred in ajax call.");
        }
      });
    });
  });
}

  4. No código anterior, digite o númerosslPort que você salvou anteriormente pelo arquivo . JSON.

No código anterior, a cadeia devolvida será processada para substituir feeds de linha de retorno de símbolos por <br> etiquetas HTML. Algumas vezes, você pode encontrar situações em que um valor de retorno que funcione perfeitamente para o .NET precisará ser ajustado no Suplemento do Office para trabalhar conforme o esperado no Suplemento VSTO . Neste caso, a API REST e a biblioteca de classes partilhadas só estão relacionadas com a devolução da cadeia. A função showUnicode() é responsável por formatar corretamente os valores de retorno para apresentação.

Permitir CORS no Suplemento do Office

A biblioteca do Office. js exige o CORS nas chamadas de saída, como a realizada na chamada ajax para o servidor de API REST. Use as etapas a seguir para permitir chamadas do Suplemento do Office para a API REST.

  1. No Gerenciador de soluções, selecione o projeto CellAnalyzerOfficeAddinWeb.

  2. No menu Ver , selecione Janela Propriedades, se a janela ainda não estiver apresentada.

  3. Na janela Propriedades, copie o valor da URL SSLe salve-a em outro local. Esta é a URL necessária para permitir o CORS.

  4. No projeto CellAnalyzerRESTAPI, abra o arquivo Startup.cs.

  5. Na parte superior do método, adicione o seguinte código ConfigureServices. Substitua a URL SSL que você copiou anteriormente para a chamada builder.WithOrigins.

    services.AddCors(options =>
{
  options.AddPolicy(MyAllowSpecificOrigins,
  builder =>
  {
    builder.WithOrigins("<your URL SSL>")
    .AllowAnyMethod()
    .AllowAnyHeader();
  });
});

    Observação

    Mantenha o final / da URL ao usá-lo no método builder.WithOrigins. Por exemplo, ele deve parecer semelhante a https://localhost:44000. Caso contrário, receberá um erro CORS no runtime.

  6. Adicione o campo a seguir à Startup classe.

    readonly string MyAllowSpecificOrigins = "_myAllowSpecificOrigins";

  7. Adicione o seguinte código ao método configure logo antes da linha de código para app.UseEndpoints.

    app.UseCors(MyAllowSpecificOrigins);

Quando terminar, Startup classe de deve ser semelhante ao código a seguir (a URL do localhost pode ser diferente).

public class Startup
{
  public Startup(IConfiguration configuration)
    {
      Configuration = configuration;
    }

    readonly string MyAllowSpecificOrigins = "_myAllowSpecificOrigins";

    public IConfiguration Configuration { get; }

    // NOTE: The following code configures CORS for the localhost:44397 port.
    // This is for development purposes. In production code, you should update this to 
    // use the appropriate allowed domains.
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddCors(options =>
        {
            options.AddPolicy(MyAllowSpecificOrigins,
            builder =>
            {
                builder.WithOrigins("https://localhost:44397")
                .AllowAnyMethod()
                .AllowAnyHeader();
            });
        });
        services.AddControllers();
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseHttpsRedirection();

        app.UseRouting();

        app.UseAuthorization();

        app.UseCors(MyAllowSpecificOrigins);

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}

Execute o suplemento

  1. No Explorador de Soluções, clique com o botão direito do rato (ou selecione sem soltar) no nó superior Solução "Analisador de Células" e selecione Definir Projetos de Arranque.

  2. Na caixa de diálogo Páginas de propriedades da solução 'Cell-Analyzer', selecione Vários projetos de inicialização.

  3. Defina a propriedade Action como Iniciar para cada um dos seguintes projetos.

    • CellAnalyzerRESTAPI
    • CellAnalyzerOfficeAddin
    • CellAnalyzerOfficeAddinWeb

  4. Escolha OK.

  5. No menu Depurar, selecione Iniciar Depuração.

O Excel será executado e fará o carregamento lateral do Suplemento do Office. Você pode testar se o serviço de API REST do localhost está funcionando corretamente, inserindo um valor de texto em uma célula e escolhendo o botão Mostrar Unicode no Suplemento do Office. Ele deve chamar a API REST e exibir os valores Unicode para os caracteres de texto.

Publicar em um serviço de aplicativo do Azure

Eventualmente, você deseja publicar o projeto da API REST na nuvem. Nas etapas a seguir, você verá como publicar o projetoCellAnalyzerRESTAPI em um serviço de aplicativo do Microsoft Azure. Confira ospré-requisitos para saber mais sobre como obter uma conta do Azure.

  1. No Explorador de Soluções, clique com o botão direito do rato (ou selecione sem soltar) no projeto CellAnalyzerRESTAPI e selecione Publicar.
  2. Na caixa de diálogo Escolha um destino de publicação, selecione Criar Novoe escolha Criar Perfil.
  3. Na caixa de diálogo Serviço de Aplicações , selecione a conta correta, se ainda não estiver selecionada.
  4. Os campos para a caixa de diálogo Serviço de Aplicativo serão definidos como padrões para a sua conta. Geralmente, as predefinições funcionam bem, mas pode alterá-las se preferir definições diferentes.
  5. Na caixa de diálogo Serviço de Aplicativo, escolha Criar.
  6. O novo perfil será exibido em uma página dePublicação. Escolha Publicar para criar e implantar o código no serviço de aplicativo.

Agora você pode testar o serviço. Abra um navegador e insira uma URL que vai diretamente para o novo serviço. Por exemplo, utilize https://<myappservice>.azurewebsites.net/api/analyzeunicode?value=test, em que myappservice é o nome exclusivo que criou para o novo Serviço de Aplicações.

Usar o Serviço de Aplicativo do Azure do Suplemento do Office

A etapa final é atualizar o código no Suplemento do Office para usar o Serviço de Aplicativo do Azure, em vez de localhost.

  1. No Gerenciador de soluções, expanda o projetoCellAnalyzerOfficeAddinWeb e abra o arquivo Home. js.

  2. Altere a constante url para usar a URL do serviço do aplicativo Azure, como mostra a linha de código a seguir. Substitua <myappservice> pelo nome exclusivo que você criou para o novo serviço de aplicativo.

    const url = "https://<myappservice>.azurewebsites.net/api/analyzeunicode?value=" + range.values[0][0];

  3. No Explorador de Soluções, clique com o botão direito do rato (ou selecione sem soltar) no nó superior Solução "Analisador de Células" e selecione Definir Projetos de Arranque.

  4. Na caixa de diálogo Páginas de propriedades da solução 'Cell-Analyzer', selecione Vários projetos de inicialização.

  5. Habilite iniciar para cada um dos projetos a seguir.

    • CellAnalyzerOfficeAddinWeb
    • CellAnalyzerOfficeAddin

  6. Escolha OK.

  7. No menu Depurar, selecione Iniciar Depuração.

O Excel será executado e fará o carregamento lateral do Suplemento do Office. Para testar se o Serviço de Aplicativo está funcionando corretamente, insira um valor de texto em uma célula e escolha Mostrar Unicode no Suplemento do Office. Ele deve chamar o serviço e exibir os valores Unicode para os caracteres de texto.

Conclusão

Neste tutorial, aprendeu a criar um Suplemento do Office que utiliza código partilhado com o suplemento VSTO original. Você aprendeu como manter o código VSTO do Office no Windows e um Suplemento do Office para o Office em outras plataformas. Você refatorou o código C # do VSTO em uma biblioteca compartilhada e o implantou em um Serviço de Aplicativo do Azure. Criou um Suplemento do Office que utiliza a biblioteca partilhada, para que não tenha de reescrever o código em JavaScript.