Partilhar via

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. 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 para 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 Gerenciador 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 Gerenciador 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 Gerenciador 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 Gerenciador 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 e Visual Studio Code do Office, também pode executar para criar yo office o projeto. As etapas são muito semelhantes.

  1. No Gerenciador 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 Gerenciador 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 Gerenciador 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 Aplicativo, 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 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 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.