| page_type | urlFragment | products | languages | extensions | description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
sample |
vsto-shared-library-excel |
|
|
|
Visual Studio Tools for Office (VSTO) add-ins can only run in Office on Windows. By migrating your code to an Office web add-in, you can expand the reach of your add-in to mobile and online platforms. Migrating the code will involve rewriting it in the JavaScript language, and also updating it to use the Office JavaScript APIs. However, you can reduce migration cost by creating a shared library and keeping some of your existing add-in code in its current language. |
Visual Studio Tools for Office (VSTO) add-ins can only run in Office on Windows. By migrating your code to an Office web add-in, you can expand the reach of your add-in to mobile and online platforms. Migrating the code will involve rewriting it in the JavaScript language, and also updating it to use the Office JavaScript APIs. However, you can reduce migration cost by creating a shared library and keeping some of your existing add-in code in its current language.
This sample includes a /start folder that accompanies the Tutorial: Migrate your VSTO Add-in to an Office web add-in with a shared code library. If you want to learn how to go through the steps for creating a shared library for an existing VSTO add-in, follow the tutorial.
The sample contains a /completed folder that contains the completed solution. If you want to explore each section of the completed solution, follow the steps in this readme to learn more.
The sample starts with an Excel VSTO add-in that provides functionality for the user to analyze a cell of text. They can view the unicode values of the text characters. The logic to convert the text to unicode is what will be shared to the web add-in.
- Excel, Outlook, Word, and PowerPoint, on Windows, Mac, and in a browser.
To set up your development environment:
- Install Visual Studio 2019.
- Install the following workloads:
- ASP.NET and web development
- .NET Core cross-platform development. Note: You need at least .NET Core version 2.2 or later to run the completed sample.
- Office/SharePoint development
- Visual Studio Tools for Office (VSTO). Note: This is an Individual component.
You'll also need a Microsoft 365 account. You might qualify for a Microsoft 365 E5 developer subscription through the Microsoft 365 Developer Program; for details, see the FAQ. Alternatively, you can sign up for a 1-month free trial or purchase a Microsoft 365 plan.
| Solution | Author(s) |
|---|---|
| Shared library VSTO migration | David Chesnut (Microsoft) |
| Version | Date | Comments |
|---|---|---|
| 1.0 | December 2, 2019 | Initial release |
THIS CODE IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.
The first step to migration is to analyze the code in your VSTO add-in. You'll want to identify each section of code as following into one of the following three categories.
- UI code that interacts with the user, such as task pane code that uses a WinForm.
- Document code that interacts with the document through the Office APIs, such as updating Excel range values.
- Business logic, such as algorithms or helper functions, that can work independently from the UI or document.
UI code and document interaction code will need to be rewritten for the Office web add-in. However, business logic code can be shared between the VSTO add-in and Office web add-in.
You'll need to install the required NuGet packages, and add test certificates for the solution to build and run correctly.
- Start Visual Studio 2019 and open the /completed/Cell-Analyzer.sln solution.
- In Solution Explorer, right-click (or select and hold) Solution 'Cell-Analyzer' and choose Restore NuGet Packages.
- In Solution Explorer, right-click (or select and hold) the Cell-Analyzer project and choose Properties.
- Choose the Signing category in the properties.
- Choose Sign the ClickOnce manifests, and then chose Create Test Certificate.
- In the Create Test Certificate dialog, enter and confirm a password. Then choose OK.
To share the business logic code, you create a class library. Then refactor the business logic and relocate it into the shared library. The advantage is that you will not need to rewrite the code in JavaScript for the Office web add-in. Later the Office web add-in will access the shared library through REST API calls.
- Start Visual Studio 2019 and open the /completed/Cell-Analyzer.sln solution.
- Expand the CellAnalyzerSharedLibrary project in the solution explorer and open the CellOperations.cs file.
The method GetUnicodeFromText is the shared function between both the VSTO add-in and Office web add-in.
- Start Visual Studio 2019 and open the /completed/Cell-Analyzer.sln solution.
- In Solution Explorer, right-click (or select and hold) the Cell-Analyzer project and choose Set as Startup Project.
- From the Debug menu, choose Start Debugging.
Note: In the completed folder, the Cell Analyzer add-in is already configured to use the shared class library.
The Office web add-in will need to access the shared library. To do this we'll provide a REST API that it can access. We can do this by creating an ASP.NET CORE application that references the class library.
- Start Visual Studio 2019 and open the /completed/Cell-Analyzer.sln solution.
- Expand the CellAnalyzerRESTAPI project in the solution explorer and open the /Controllers/AnalyzeUnicodeController.cs file.
The method AnalyzeUnicode is a wrapper that calls into the shared class library to perform the actual operation.
- Start Visual Studio 2019 and open the /completed/Cell-Analyzer.sln solution.
- In Solution Explorer, right-click (or select and hold) the CellAnalyzerRESTAPI project and choose Set as Startup Project.
- From the Debug menu, choose Start Debugging.
- In the browser that opens, enter the following URL: https://localhost:44323/api/analyzeunicode?value=test
You should see the list of characters returned along with each unicode value.
The Office web add-in must be created and then modified to match the VSTO add-in UI and document interactions as much as possible. For UI you will need to create similar controls using HTML, CSS, or your favorite library. You will also need to rewrite code that interacts with the document to use the Office JavaScript API.
- Start Visual Studio 2019 and open the /completed/Cell-Analyzer.sln solution.
- Expand the CellAnalyzerRESTAPI project in the solution explorer and open the /Controllers/AnalyzeUnicodeController.cs file.
The method AnalyzeUnicode is a wrapper that calls into the shared class library to perform the actual operation.
- Start Visual Studio 2019 and open the /completed/Cell-Analyzer.sln solution.
- In Solution Explorer, right-click (or select and hold) the top node Solution 'Cell-Analyzer' and choose Set Startup Projects.
- In the Solution 'Cell-Analyzer' Property Pages dialog, select Multiple startup projects.
- Enable the Start action for each of the following projects.
- CellAnalyzerRESTAPI
- CellAnalyzerWebAddinWeb
- CellAnalyzerWebAddin
- Choose OK.
- From the Debug menu, choose Start Debugging.
Excel will run and sideload the Office web add-in.
This readme file has you create test certificates to run the Cell-Analyzer project. These are for testing and development purposes only. Do not reuse them in your own code solutions or in production environments.
In the Startup.cs file, the ConfigureServices method updates the CORS policy to allow port localhost:44368. This is for development purposes. In production code you should update this to use the appropriate allowed domains.
The Cell analyzer REST API project is configured to support CORS requests from https://localhost:44368 (the Office web add-in.) This is only for development purposes. In production code, you should configure CORS to support your deployed Office web add-in endpoint.
- Did you experience any problems with the sample? Create an issue and we'll help you out.
- We'd love to get your feedback about this sample. Go to our Office samples survey to give feedback and suggest improvements.
- For general questions about developing Office Add-ins, go to Microsoft Q&A using the office-js-dev tag.
Copyright (c) 2020 Microsoft Corporation. All rights reserved.
This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.