Tutorial: Compartilhar código entre um suplemento VSTO e um suplemento do Office usando uma biblioteca de código compartilhada

Use este tutorial para manter seu suplemento VSTO existente enquanto cria um Suplemento do Office equivalente para clientes multiplataforma. Você moverá a lógica de negócios reutilizável para uma biblioteca .NET compartilhada e a chamará do Suplemento do Office por meio de uma API REST.

Os suplementos do Visual Studio Tools para Office (VSTO) são ótimos para estender o Office e fornecer soluções para sua empresa 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. Você não pode executar suplementos VSTO no Mac, na Web ou em plataformas móveis.

Importante

Não há suporte para suplementos COM e VSTO no novo Outlook no Windows. Esses suplementos ainda têm suporte no cliente de desktop clássico do Outlook no Windows. Para saber mais, confira 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 um suplemento COM ou VSTO existente.

No entanto, é melhor evitar reescrever todo o código do 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 orienta você pelas etapas de identificação e compartilhamento de código comum entre o Suplemento VSTO e um Suplemento moderno do Office. Ele usa um exemplo de Suplemento VSTO muito simples para as etapas para que você possa se concentrar nas habilidades e técnicas necessárias para trabalhar com 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. Instale o Visual Studio 2022.
  2. Instale as cargas de trabalho a seguir.
    • ASP.NET e desenvolvimento na Web
    • Desenvolvimento multiplataforma do .NET Core
    • Desenvolvimento do Office/SharePoint
    • Os seguintes componentesindividuais.
      • Visual Studio Tools para Office (VSTO)
      • Runtime do .NET Core 9.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 você migrará. Sua meta é migrar o Suplemento VSTO para um Suplemento do Office moderno, quando possível.

Observação

O exemplo usa C#, mas você pode aplicar as técnicas deste tutorial a um Suplemento VSTO escrito em qualquer linguagem .NET.

  1. Baixe o exemplo de Suplemento de biblioteca compartilhada do Suplemento VSTO para o Office em uma pasta de trabalho no computador.
  2. Inicie o Visual Studio 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 texto e escolher Mostrar Unicode. Na seção Resultado , o suplemento exibe uma lista de cada caractere no texto com seu número Unicode correspondente.

O suplemento VSTO do Analisador de Célula em execução no Excel com o botão 'Mostrar unicode' e a seção Resultado vazia.

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 projeto se divide em três tipos de código.

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 essas diferenças, você não pode compartilhar o código da interface do usuário com o suplemento do Office. A interface do usuário precisa ser recriada no JavaScript.

Código do documento

No VSTO, o código interage com o documento por meio de objetos .NET, como Microsoft.Office.Interop.Excel.Range. No entanto, os Suplementos do Office usam a biblioteca JavaScript do Office (também chamada de Office.js). Embora sejam semelhantes, eles não são exatamente os mesmos. Portanto, novamente, você não pode compartilhar o código de interação de documentos 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;
}

Usando essa abordagem, você pode ver que uma seção de código pode ser compartilhada com o suplemento do Office. O código a seguir precisa ser refatorado em uma 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 mouse (ou selecione e segure) a solução no Gerenciador de Soluções e escolha 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 use a biblioteca de classes do .NET Core porque ela não funcionará com seu 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 em seu valor padrão.
    • 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, atualize o Suplemento VSTO para usar a biblioteca de classes. É importante que ambos os suplementos usem a mesma biblioteca de classe compartilhada para que futuras correções de bugs e recursos sejam implementados em um único local.

  1. No Gerenciador de Soluções, clique com o botão direito do mouse (ou selecione e segure) no projeto Cell-Analyzer e escolha Adicionar referência.

  2. Selecione CellAnalyzerSharedLibrarye escolha OK.

  3. Em Gerenciador de Soluções, expanda o projeto Cell-Analyzer, clique com o botão direito do mouse (ou selecione e segure) o arquivo CellAnalyzerPane.cs e escolha Exibir 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 compartilhada diretamente porque ambos são projetos .NET. No entanto, o Suplemento do Office não pode usar o .NET diretamente porque usa JavaScript. Em seguida, crie um wrapper da API REST. Isso permite que o Suplemento do Office chame uma API REST, que chama a biblioteca de classes compartilhada.

  1. No Gerenciador de Soluções, clique com o botão direito do mouse (ou selecione e segure) no projeto do Analisador de Célula e escolha 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 mouse (ou selecione e segure) Dependências e escolha Adicionar referência.

  9. Selecione CellAnalyzerSharedLibrarye escolha OK.

  10. Clique com o botão direito do mouse (ou selecione e segure) na pasta Controladores e escolha Adicionar > Controlador.

  11. Na caixa de diálogo Adicionar Novo Item de Scaffolded , escolha Controlador de API - Vazio e, em seguida, escolha Adicionar.

  12. Na caixa de diálogo Adicionar Controlador de API Vazio , nomeie o controlador como AnalyzeUnicodeController e escolha 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 mouse (ou selecione e segure) no projeto CellAnalyzerRESTAPI e escolha Definir como Projeto de Inicialização.

  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 você estiver familiarizado com o gerador Yeoman para Suplementos do Office e o Visual Studio Code, também poderá executar yo office para compilar o projeto. As etapas são muito semelhantes.

  1. No Gerenciador de Soluções, clique com o botão direito do mouse (ou selecione e segure) na solução Cell-Analyzer e escolha 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 em seu valor padrão.
    • 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 sã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, insira o número sslPort que você salvou do arquivo launchSettings.json .

No código anterior, a string retornada é processada para substituir feeds de linha de retorno de carro por <br> tags HTML. Às vezes, um valor retornado que funciona no .NET para o suplemento VSTO precisa ser ajustado no lado do suplemento do Office para apresentação. Nesse caso, a API REST e a biblioteca de classes compartilhadas retornam apenas a cadeia de caracteres. A showUnicode() função formata para exibiçã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 Exibir , escolha Janela de Propriedades, se a janela ainda não estiver sendo exibida.

  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. Certifique-se de substituir a builder.WithOrigins chamada pela URL SSL que você copiou anteriormente.

    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, você receberá um erro CORS em tempo de execução.

  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 Gerenciador de Soluções, clique com o botão direito do mouse (ou selecione e segure) o nó superior Solução 'Cell-Analyzer' e escolha Definir Projetos de Inicialização.

  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 da API REST do localhost está funcionando corretamente inserindo um valor de texto em uma célula e escolhendo Mostrar Unicode no Suplemento do Office. Ela 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 Gerenciador de Soluções, clique com o botão direito do mouse (ou selecione e segure) no projeto CellAnalyzerRESTAPI e escolha 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 do Serviço de Aplicativo, selecione a conta correta, se ela 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, os padrões funcionam bem, mas você pode alterá-los se preferir configuraçõ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, use https://<myappservice>.azurewebsites.net/api/analyzeunicode?value=test, em que myappservice é o nome exclusivo criado para o novo Serviço de Aplicativo.

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 Gerenciador de Soluções, clique com o botão direito do mouse (ou selecione e segure) o nó superior Solução 'Cell-Analyzer' e escolha Definir Projetos de Inicialização.

  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, você aprendeu a criar um suplemento do Office que usa código compartilhado 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. Você criou um Suplemento do Office que usa a biblioteca compartilhada, para que você não precise reescrever o código em JavaScript.

  • Last updated on