Skip to content

Commit 599e667

Browse files
davidchesnutdavidchesnut
authored
VSTO Shared code migration(#59)
* initial commit * draft readme and start completed folders * readme and minor updates * changing folder name * added solution setup steps * incorporated review feedback * added security notes and minor fixes * remove unnecessary scripts * added jquery cdn * removed unneeded function * renaming Office add-in project * Update README.md * update link * update sample list * reorganize sample list * simplify descriptions * simplify descriptions * fix header
1 parent e2d5e62 commit 599e667

File tree

160 files changed

+84751
-7
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

160 files changed

+84751
-7
lines changed

‎README.md

+11-7
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,18 @@
22

33
Office Add-ins PnP is a community driven effort that helps developers extend, build, and provision customizations for the Office platform. The source is maintained on this GitHub repo where anyone can participate. You can provide contributions to the samples, reusable components, and documentation. Office Add-ins PnP is owned and coordinated by Office engineering teams, but the work is done by the community for the community.
44

5-
## List of recent samples
5+
## List of samples
66

7-
- [Use storage techniques to access data from an Office Add-in when offline](https://github.com/OfficeDev/PnP-OfficeAddins/tree/master/Samples/Excel.OfflineStorageAddin). Demonstrates how you can implement localStorage to enable limited functionality for your Office Add-in when a user experiences lost connection.
8-
- **Authentication and authorization:** We're adding a new auth section and have two new samples.
9-
- [Office Add-in auth to Microsoft Graph](https://github.com/OfficeDev/PnP-OfficeAddins/tree/master/Samples/auth/Office-Add-in-Microsoft-Graph-ASPNET). Learn how to build a Microsoft Office Add-in that connects to Microsoft Graph, finds the first three workbooks stored in OneDrive for Business, fetches their filenames, and inserts the names into an Office document using Office.js.
10-
- [Outlook Add-in auth to Microsoft Graph](https://github.com/OfficeDev/PnP-OfficeAddins/tree/master/Samples/auth/Outlook-Add-in-Microsoft-Graph-ASPNET). Learn how to build a Microsoft Outlook Add-in that connects to Microsoft Graph, finds the first three workbooks stored in OneDrive for Business, fetches their filenames, and inserts the names into a new message compose form in Outlook.
11-
- [Custom function batching pattern](https://github.com/OfficeDev/PnP-OfficeAddins/tree/master/Excel-custom-functions/Batching). If your custom functions call a remote service you may want to use a batching pattern to reduce the number of network calls to the remote service. This is useful when a spreadsheet recalculates and it contains many of your custom functions. Recalculate will result in many calls to your custom functions, but you can batch them into one or a few calls to the remote service.
12-
- [Custom function storage](https://github.com/OfficeDev/PnP-OfficeAddins/tree/master/Excel-custom-functions/Storage) for custom functions. Custom functions and task panes cannot directly communicate with each other. See how to use the Storage object to send data between custom functions and task panes. This is especially useful for sharing an access token.
7+
| Date | Name | Description |
8+
| ------------------ | -------------- | ------------ |
9+
| January 29, 2020 | [Use a shared library to migrate your Visual Studio Tools for Office add-in to an Office web add-in](https://github.com/OfficeDev/PnP-OfficeAddins/tree/master/Samples/VSTO-shared-code-migration) | Provides a strategy for code reuse when migrating from VSTO Add-ins to Office Add-ins. |
10+
| November 12, 2019 | [Get OneDrive data using Microsoft Graph and msal.js in an Office Add-in](https://github.com/OfficeDev/PnP-OfficeAddins/tree/master/Samples/auth/Office-Add-in-Microsoft-Graph-React) | Learn how to build a Microsoft Office Add-in, as a single-page application (SPA) with no backend, that connects to Microsoft Graph, and access workbooks stored in OneDrive for Business to update a spreadsheet. |
11+
| October 2, 2019 | [Integrate an Azure function with your Excel custom function](https://github.com/OfficeDev/PnP-OfficeAddins/tree/master/Excel-custom-functions/AzureFunction) | Learn how to integrate Azure functions with custom functions to move to the cloud or integrate additional services. |
12+
| September 30, 2019 | [Dynamic DPI code samples](https://github.com/OfficeDev/PnP-OfficeAddins/tree/vstoshared/Samples/dynamic-dpi) | A collection of samples for handling DPI changes in COM, VSTO, and Office Add-ins. |
13+
| July 19, 2019 | [Use storage techniques to access data from an Office Add-in when offline](https://github.com/OfficeDev/PnP-OfficeAddins/tree/master/Samples/Excel.OfflineStorageAddin) | Demonstrates how you can implement localStorage to enable limited functionality for your Office Add-in when a user experiences lost connection. |
14+
| May 1, 2019 | [Office Add-in auth to Microsoft Graph](https://github.com/OfficeDev/PnP-OfficeAddins/tree/master/Samples/auth/Office-Add-in-Microsoft-Graph-ASPNET) | Learn how to build a Microsoft Office Add-in that connects to Microsoft Graph, and access workbooks stored in OneDrive for Business to update a spreadsheet. |
15+
| May 1, 2019 | [Outlook Add-in auth to Microsoft Graph](https://github.com/OfficeDev/PnP-OfficeAddins/tree/master/Samples/auth/Outlook-Add-in-Microsoft-Graph-ASPNET). | Learn how to build a Microsoft Outlook Add-in that connects to Microsoft Graph, and access workbooks stored in OneDrive for Business to compose a new email message. |
16+
| May 1, 2019 | [Custom function batching pattern](https://github.com/OfficeDev/PnP-OfficeAddins/tree/master/Excel-custom-functions/Batching)| Batch multiple calls into a single call to reduce the number of network calls to a remote service.|
1317

1418
## Learn more
1519

‎Samples/VSTO-shared-code-migration/README.md

+178
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
---
2+
page_type: sample
3+
products:
4+
- office-excel
5+
- office-365
6+
languages:
7+
- javascript
8+
- csharp
9+
extensions:
10+
contentType: samples
11+
technologies:
12+
- Add-ins
13+
createdDate: 01/29/2020 1:25:00 PM
14+
description: ""
15+
---
16+
17+
# Use a shared library to migrate your Visual Studio Tools for Office add-in to an Office web add-in
18+
19+
![Sharing code between a VSTO Add-in and an Office Web Add-in](shared-code-library-migration.png)
20+
21+
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.
22+
23+
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](https://docs.microsoft.com/office/dev/add-ins/tutorials/migrate-vsto-to-office-add-in-shared-code-library-tutorial). 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.
24+
25+
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.
26+
27+
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.
28+
29+
![The Cell Analyzer VSTO Add-in running in Excel](cell-analyzer.png)
30+
31+
## Applies to
32+
33+
- Excel, Outlook, Word, and PowerPoint, on Windows, Mac, and in a browser.
34+
35+
## Prerequisites
36+
37+
To set up your development environment:
38+
39+
1. Install [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/).
40+
2. Install the following workloads:
41+
- ASP.NET and web development
42+
- .NET Core cross-platform development. **Note:** You need at least .NET Core version 2.2 or later to run the completed sample.
43+
- Office/SharePoint development
44+
- Visual Studio Tools for Office (VSTO). **Note:** This is an **Individual** component.
45+
46+
You will also need an Office 365 account. You can join the [Office 365 Developer Program](https://aka.ms/devprogramsignup) that includes a free 1 year subscription to Office 365.
47+
48+
## Solution
49+
50+
Solution | Author(s)
51+
---------|----------
52+
Shared library VSTO migration | David Chesnut (**Microsoft**)
53+
54+
## Version history
55+
56+
Version | Date | Comments
57+
---------| -----| --------
58+
1.0 | December 2, 2019 | Initial release
59+
60+
## Disclaimer
61+
62+
**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.**
63+
64+
----------
65+
## Analyze your VSTO add-in
66+
67+
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.
68+
69+
1. UI code that interacts with the user, such as task pane code that uses a WinForm.
70+
2. Document code that interacts with the document through the Office APIs, such as updating Excel range values.
71+
3. Business logic, such as algorithms or helper functions, that can work independently from the UI or document.
72+
73+
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.
74+
75+
## Prepare the solution to run
76+
77+
You'll need to install the required NuGet packages, and add test certificates for the solution to build and run correctly.
78+
79+
1. Start Visual Studio 2019 and open the **/completed/Cell-Analyzer.sln** solution.
80+
2. In **Solution Explorer**, right-click **Solution 'Cell-Analyzer'**, and choose **Restore NuGet Packages**.
81+
3. In **Solution Explorer**, right-click the **Cell-Analyzer** project, and choose **Properties**.
82+
4. Choose the **Signing** category in the properties.
83+
5. Choose **Sign the ClickOnce manifests**, and then chose **Create Test Certificate**.
84+
6. In the **Create Test Certificate** dialog, enter and confirm a password. Then choose **OK**.
85+
86+
## Part 1: Share code in a class library
87+
88+
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.
89+
90+
### Explore the shared class library
91+
92+
1. Start Visual Studio 2019 and open the **/completed/Cell-Analyzer.sln** solution.
93+
2. Expand the **CellAnalyzerSharedLibrary** project in the solution explorer and open the **CellOperations.cs** file.
94+
95+
The method **GetUnicodeFromText** is the shared function between both the VSTO add-in and Office web add-in.
96+
97+
### Run the VSTO add-in with the shared class library
98+
99+
1. Start Visual Studio 2019 and open the **/completed/Cell-Analyzer.sln** solution.
100+
2. In **Solution Explorer** right-click the **Cell-Analyzer** project and choose **Set as Startup Project**.
101+
3. From the **Debug** menu, choose **Start Debugging**.
102+
103+
> **Note:** In the completed folder, the Cell Analyzer add-in is already configured to use the shared class library.
104+
105+
## Part 2: Create a REST API wrapper for shared code
106+
107+
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.
108+
109+
### Explore the REST API project
110+
111+
1. Start Visual Studio 2019 and open the **/completed/Cell-Analyzer.sln** solution.
112+
2. Expand the **CellAnalyzerRESTAPI** project in the solution explorer and open the **/Controllers/AnalyzeUnicodeController.cs** file.
113+
114+
The method **AnalyzeUnicode** is a wrapper that calls into the shared class library to perform the actual operation.
115+
116+
### Run the REST API project
117+
118+
1. Start Visual Studio 2019 and open the **/completed/Cell-Analyzer.sln** solution.
119+
2. In **Solution Explorer** right-click the **CellAnalyzerRESTAPI** project and choose **Set as Startup Project**.
120+
3. From the **Debug** menu, choose **Start Debugging**.
121+
4. In the browser that opens, enter the following URL: **https://localhost:44323/api/analyzeunicode?value=test**
122+
123+
You should see the list of characters returned along with each unicode value.
124+
125+
## Part 3: The Office web add-in
126+
127+
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.
128+
129+
### Explore the Office web add-in project
130+
131+
1. Start Visual Studio 2019 and open the **/completed/Cell-Analyzer.sln** solution.
132+
2. Expand the **CellAnalyzerRESTAPI** project in the solution explorer and open the **/Controllers/AnalyzeUnicodeController.cs** file.
133+
134+
The method **AnalyzeUnicode** is a wrapper that calls into the shared class library to perform the actual operation.
135+
136+
### Run the Office web add-in project
137+
138+
1. Start Visual Studio 2019 and open the **/completed/Cell-Analyzer.sln** solution.
139+
2. In **Solution Explorer** right-click the top node **Solution 'Cell-Analyzer'** and choose **Set Startup Projects**.
140+
3. In the **Solution 'Cell-Analyzer' Property Pages** dialog, select **Multiple startup projects**.
141+
4. Enable the Start action for each of the following projects.
142+
- CellAnalyzerRESTAPI
143+
- CellAnalyzerWebAddinWeb
144+
- CellAnalyzerWebAddin
145+
5. Choose **OK**.
146+
6. From the **Debug** menu, choose **Start Debugging**.
147+
148+
Excel will run and sideload the Office web add-in.
149+
150+
## Security notes
151+
152+
### Cell-Analyzer notes
153+
154+
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.
155+
156+
### CellAnalyzerRESTAPI notes
157+
158+
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.
159+
160+
### CellAnalyzerRESTAPI notes
161+
162+
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.
163+
164+
## Questions and comments
165+
166+
We'd love to get your feedback about this sample. You can send your feedback to us in the Issues section of this repository. Questions about developing Office Add-ins should be posted to Stack Overflow. Ensure your questions are tagged with [office-js].
167+
168+
## Additional resources
169+
170+
- [Office Add-ins documentation](https://docs.microsoft.com/office/dev/add-ins/overview/office-add-ins)
171+
172+
## Copyright
173+
174+
Copyright (c) 2020 Microsoft Corporation. All rights reserved.
175+
176+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
177+
178+
<img src="https://telemetry.sharepointpnp.com/pnp-officeaddins/samples/vsto-shared-library-excel" />

‎Samples/VSTO-shared-code-migration/cell-analyzer.png

9.43 KB
Loading

0 commit comments

Comments
 (0)