Tag: VSCode

Developing in Linux on Windows

David E. Craig1 Comment

I have been working more and more with Linux lately. The job as a Program Manager has put some of my skills to the test. Oddly, I actually taught a semester of Linux back in my “college professor days.” And despite the kicking and screaming, funny enough, I am close to becoming a novice beginner at it.

Last year, I took the deep dive, spending nearly 100% of my personal time in Linux – command line and UI wise. I had an Ubuntu VM in the cloud that I worked with and repurposed on one of my old laptops with a distro of Elementary OS (essentially a MacOS like shell on top of Ubuntu).

Well, recently, I have been playing about with the Windows Subsystem for Linux. In the early days this was what I called a novelty. You could open a command prompt and start bashing out Linux commands and feeling totally geeky 🤓. However, recently, I found that you can now run Linux Applications in a window from Windows 11. This was a bit of a game changer, as now I can run Linux and Windows (side-by-side).

So, I just got through developing and testing an Office JS add-in (which I just published to the store) from Linux using VS Code and Microsoft Edge. It will hopefully be released soon, and I will blog it here (Send to Trello for Outlook Add-in).

Here is how I did it:

  1. First, I would suggest installing Windows Terminal. I can spend a whole blog post on this and might, but it allows you to run CMD, PowerShell and BASH all side by side in tabs. It is awesome.
  2. Open Terminal and install WSL. From a PowerShell tab type “wsl –install”. By default, this will put Ubuntu 20 (behind the scenes) on your system.
  3. Once installed and you restart the Windows Terminal App, you should see Ubuntu as an option for opening a new Tab.
  4. Select that. If it is your first time, you will need to supply it with a username and password.
  5. Once setup, you simply need to start installing apps:
    • Type: “sudo apt update” to start updating the apps, this is like “Windows Update” for Linux.
    • Next, type: “sudo apt install x11-apps -y” to get the basic software installed.
    • Next, you will want to install Microsoft Edge:
      • To install Edge use the code from this page: https://www.microsoftedgeinsider.com/en-us/download?platform=linux-deb (scroll down past the ‘download’ links).
      • Before you run it, you will want to type: “sudo su” and sign in. This signs you in as SUPER USER so that you can do things as an administrator.
      • After it is installed type “exit” to return to normal user mode.
    • Finally, install VS Code, like this: in the Terminal Window, type: “microsoft-edge” which will open Edge. From there go to Bing, search for “install VSCode on Linux” and it should not be too difficult to follow the steps you find. But to help out a bit… 😊 Follow the steps for Ubuntu, here: https://code.visualstudio.com/docs/setup/linux.
  6. Now you can type “code” in the Linux command prompt and VSCode for Linux will open in a separate window. From there you can build your application and test it in Edge for Linux as well. That is what I did.

The coup-de-grace, it places these applications right on your START menu:

So, a friend asked me…”Uh, so.. like.. why?” I answered, “Uh… Because, I can!” 🤓

It has been a fun journey, learning something new and as it turns out, it has come in handy quite a few times in the new role as different aspects of the system we are developing cross paths with Linux. I also have a sneaky suspicion that this Windows/Linux integration lines are going to get a bit more “blurred” in the coming years (100% personal opinion).

Yeah! A Trello Type Definitions File

David E. CraigLeave a comment

To date I have created four Trello Power-Ups that I use every day to fill a gap that I need in order to scrum my life’s “backlog.” I was first turned towards Trello when I read Deep Work by Cal Newport. Since then I created:

Each time I created a Power-Up, I found myself going back to the documentation over and over again for the most trivial items. So, I finally sat down and hacked out a type definitions file based on the existing Trello Power-Up Documentation.

You can find all the information about the type library I created here:

https://github.com/davecra/Trello-Power-Up-TypeDefs

Office Web Add-in Debugging in VS Code

David E. CraigLeave a comment

Another recent announcement that has me excited is the ability to debug Office Web Add-ins directly from VS Code. Before this recent announcement, it was a hit or miss proposition. There was Visual Studio 2019, that did a pretty good job. But I liked the lightweight simplicity of VS Code. Visual Studio 2019 seemed too too heavy-weight. It’s hard to put my finger on how or why, but I really enjoy VS Code for Web Add-in development so much better. Except for debugging…

So, to debug, I actually did most of my dev/test in the web versions of Office (Excel online, Outlook online, etc.). Then came the Edge Developer Tools Preview which helped debug task pane add-ins in the full clients. But that did not help with things like the On Send event in Outlook or other UI-less functions. So, it was a struggle at times.

Now that has all changed!!!

The process is a tad more complicated than I like, but it does work. Essentially, you need to:

  1. Run VS Code as administrator
  2. Install the extension in VS Code by pressing CTRL + SHIFT + X and searching for the “Microsoft Office Add-in Debugger”
  3. Add the following code to the .vscode\launch.json file to enable Office Debugging in your project. You will need to update line #7, and replace the uppercase HOST text with the host application for your Office add-in.
{ 
   "type": "office-addin", 
   "request": "attach", 
   "name": "Attach to Office Add-ins", 
   "port": 9222, 
   "trace": "verbose", 
   "url": "https://localhost:3000/taskpane.html?_host_Info=HOST$Win32$16.01$en-US$$$$0", "webRoot": "${workspaceFolder}", 
   "timeout": 45000 
}

NOTE: If you create a new Office project with Yeoman, you will not need to add this line, it will be part of the default template going forward.

  1. Press CTRL+SHIFT+D to then open the Debug pane, select Attach to Office Add-in option from the drop down list at the top of the pane, and press F5 to start debugging.
  2. You can now set breakpoints, see variable values, etc.
Attach to Office Add-ins menu option

How to Fix IntelliSense in VSCode for OfficeJS

David E. CraigLeave a comment

I spent the better part of this morning trying to figure out why a new Yeoman generated Outlook add-in was not working with IntelliSense in VSCode. I would type “Office.” and nothing would appear. I would press CTRL+{SPACE} and still nothing.

After a lot of digging and comparing projects that did work to those that did not, I found that the @types were missing. So I then installed @types/office-js:

npm install @types/office-js

Once I did this, viola! IntelliSense started working like a charm. From my experience this has happened to me a few different times, in these given scenarios:

  • Moving an OfficeJS project from VS2017 to VSCode
  • Moving a Script Lab project to VSCode
  • Creating a blank OfficeJS project from scratch with just two files (manifest and webpage).

In my continued research I found that the way VSCode handles types is through NPM and you need to have data type definition files to get it all to work, that is why you need to install both NPM and the OfficeJS @types to get this to work. Per this page:  https://code.visualstudio.com/Docs/languages/javascript

Automatic Type Acquisition (ATA) uses npm, the Node.js package manager, to install and manage Type Declaration (typings) files. To ensure that Automatic Type Acquisition works properly, first ensure that you have npm installed on your machine.

Secondly to that, for OfficeJS development, make sure you have @types/office-js.

Getting Started as an OfficeJS Developer

David E. Craig1 Comment

At the MVP Summit 2018, I have had a number of conversations with various MVP’s that there really should be more documentation on how to get started with OfficeJS from scratch. Like web developer – from scratch.

So, this blog post is my attempt to get you started as if you have little to no web developer experience. The hope is that once you have read this and studied the linked content you will be able to:

  • Write HTML and JavaScript
  • Understand what JQuery is and how to use it
  • Setup your VSCode environment
  • Identify the key parts of an add-in (source code files)
  • Begin writing, and debugging your own code.

To get started, if you are completely new to web development (or even a little rusty and need a refresher), you might want to read the following articles/tutorials. If you already know this stuff, then you can move on:

 

NOTE: From these links you need to come away with an understanding of these basic fundamental concepts that are used heavily in OfficeJS:

  1. How JavaScript and HTML work together
  2. The HTML DOM model
  3. How to write HTML and define controls (buttons, text boxes, etc.) with an id
  4. How to use JQuery(*) to get a reference to a control on the HTML page and then manipulate it with JavaScript.

(*) JQuery is simply a library that, for simplicity sake, makes it easy for you to access and manipulate HTML controls via the DOM. You access it with a “$” character. This is why you might see so many “$”‘s in the sample/example code out there.

Once you know the basics of creating a web page, and manipulating it, you can then begin by setting up VSCode and learning how to code OfficeJS solutions. As for development environments, there are many out there, and many are nearly the same, but I suggest VSCode because it is simply a better environment to learn “webby” development. Especially if you are on a Mac. With that said, you will want to:

  1. Setup and configure VSCode
  2. Start learning Office from the new quick start and tutorials on docs.office.com.
  3. You can also stick to the basics (no development environment needed) if you install and use Script Lab.

NOTE: A fundamental concept you need to come away with after working through the tutorials is to understand the “parts” of an add-in. I think the best way to understand the PARTS of an add-in:

  • All you really need for an OfficeJS solution are two files. A manifest and an HTML file.

To understand the anatomy of an add-in, you can read this post where I describe the most basic add-in you can create. Here is a simplified explanation to get your started:

  • The Manifest – an XML file that defines to Office your add-in. It defines things like the name, a unique id (GUID), the platform and app it supports, and most importantly your Ribbon (text, icons, etc), and what happens when you click those buttons. Specifically, it tell Office where to navigate when that button is clicked. Then this XML file is what gets “installed” in your Office app. Office reads it, places the button(s) on the Ribbon which loads the defined web page when clicked.
  • The HTML file – this contains “script” tags which point to all your code, supporting libraries (like JQuery) which similar to VBA/VSTO references. The HTML page also contains your Task Pane user interface (buttons, etc.).
  • The JavaScript file – This is your code, which will contain an Office.initialize() function that Office locates and executes when the HTML page is loaded. This can be a separate file or like the most basic add-in an inline script tag in your HTML file.

The entire load and run process for an add-in works like this:

  • The Manifest is loaded by Office and adds a button to the ribbon.
  • When the button is clicked, the HTML file specified in the manifest is loaded in the task pane.
  • When the HTML file is loaded, all the script tags (references and your own JS file) are loaded.
  • Once all the scripts are loaded, Office locates the Office.initialize() function and executes it.
  • It is in this code block that you can initialize your controls, like buttons on the HTML page, and what happens when the user clicks them.

Once you have your VSCode development environment setup for Office, and you are ready to start your first project, follow these steps I outlined for using the Yeoman generator.

I hope this is enough to get even the most novice non-web developer going. If you have any questions, please post them below. If there is any additional content you would like to see, please let me know.

The last thing I will leave you with is to answer an interesting question that arose this week:

Why would I learn to develop in OfficeJS? I am not interested in just making a web widget for Excel.

I think this is a common misconception. Office 365 Web Add-ins (OfficeJS) are at all not like Windows Vista Sidebar Gadgets for Office. They are actually quite powerful and there are many useful scenarios. Here are a few:

  • Integration with internal applications like CRM
  • Document tagging, or placing metadata on parts of the document, possibly linked with internal systems, controls or processes
  • Document building, either interactively through a task pane or dialog or from predefined rules
  • Advanced content editing, identifying and replacing specific content based on more complex rules than simple search/replace
  • Sending data from the document for more complex analysis and/or manipulation via back-end services and then updating the document with the results.

Once you delve a bit more into the object model and the capabilities, you will learn that you do not always have to open a task pane. You can open a dialog instead. Or, you can have no user interface at all, just have a button click on the ribbon perform work against the document like a macro used to do.

And here is another thought: Office is used by one-billion people world-wide across each of the supported platforms of Windows, Mac, web, iOS, and Android. The goal of these add-ins is to support the same code base (mostly) across all of these different platforms. You really can write-once/run-anywhere. You can build an add-in and then place it in the Microsoft Store and have it reach a huge audience. Do you need more of a reason to get started?

Happy coding.

How to Configure VSCode for Office Development

David E. Craig6 Comments

I thought I had written this some time ago, but I guess I did not. So here goes…

NOTE: First, I want to state that if you are creating applications for the full Office clients, it might be best to continue using Visual Studio 2017 as you are able to debug directly in these clients with much more ease than you can from VSCode.

Some might find it hard to believe, but I have been geeking out hard and using VSCode to develop OfficeJS (Office 365 Web Add-ins). I find it a very useful, light client, where I am able to focus on just the basics. When combined with tools like Node Package Manager (NPM), browser sync, Yoeman and Git, you have a surprisingly robust development environment what makes doing things delightfully easy. wlEmoticon-hotsmile.png But it was not always this way, I had a learning curve and it took me a while to get it all setup and running correctly. I am not saying it was hard, just… different. So I channeled my inner geek and much to his delight, it turned out for the better.

So as I stated the challenge was getting it all setup. This is going to be very different, especially if you are coming from the Visual Studio 2017 world (much more so, from the VBA world). So, here are the step by step instructions I use for getting my VSCode development environment all configured for Office Development:

  1. Download and install VSCode: https://code.visualstudio.com/ .
  2. Download and install Node to get Node Package Manager (NPM): https://nodejs.org/en/download/. On this page you will want to download the Windows/MSI/64-bit version.
  3. Download and install Git: https://git-scm.com/download. On this page you will want to make sure you select to install the latest which is from the link in the upper right of the page.
  4. Now we have the basic packages we need in order to begin development. What we need to do now is install the Yeoman generator. To do this:
    • Open VSCode
    • Press CTRL+`. This will open the console window. Alternatively you can go to the View menu and click Integrated Terminal
    • Switch to the Terminal in the Console and then type the following command: npm install —global yo
  5. Now you are ready to start generating OfficeJS add-ins from VSCode, and these steps will walk you through the first one:
    • Type: yo office sample-1
    • Once you do this the scaffold generator will kick in and ask you a few questions. Answer them as I have, in bold, below:? Would you like to create a new subfolder for your project? No
      ? Which Office client application would you like to support? Excel
      ? Would you like to create a new add-in? Yes, I need to create a new web app and manifest file for my add-in.
      ? Would you like to use TypeScript? No
      ? Choose a framework: Jquery
      ? Would you like to open it now while we finish creating your project? Yes
    • Once complete you will not have a solution folder called sample1 under your user profile c:\users\<yourname>\sample-1, but the project will not be open in VSCode, yet…
    • To open your project on the File menu, click Open Folder and then browse to and open the sample1 folder, then press Select Folder. NOTE: If you are coming from Visual Studio where the tree of solution files appears on the right side of the screen, the “Explorer” in VSCode appears on the left and it is actually a listing of ALL files and ALL folders in the solution directory.
    • You will see the code files for your project on the left hand side in the Explorer. The key files of importance to you, getting started will be:
      • sample-1-manifest.xml – this is your manifest for publishing your add-in.
      • index.html – this is your primary page or “task pane” for your add-in.
    • In this example I will not have you edit any of the files, but the basics are completely provided to build a solution. At this point we will check this into Git. Press CTRL+SHIFT+G. This will open the Source Control repository page. Click the icon to the right of the words Source Control, to Initialize Repository. This will open the folder to your solution, simply click Initialize Repository. You can now work with Git to manage your project. I will not go into more detail, but if you are interested, please watch this video: https://git-scm.com/video/what-is-git
    • Finally, we are ready to debug. But first, if you are on Windows 10, and you use Edge or Internet Explorer as your default browser, I would strongly suggest using the Google Chrome browser because the debug tools are so much better. However, there is one change you need to make:
      • Open the bsconfig.json file in the Explorer
      • At the top of the configuration you need to place this line: “browser”: “chrome”, so that the file looks like this: 
        {
    "browser": "chrome",
    "ui": {...
    • To debug, press CTRL+` to open or return to the Integrated Terminal. Type: npm start. This will open your project in Chrome. You might get a warning that the site is not trusted, click Advanced and select to trust anyway / continue.
    • Open another tab and browse to office365.com. Once there, log into your account. On the Office menu in the upper left, click Excel. On the Insert menu, click Office Add-ins. In the upper right of the dialog, click Upload my add-in. Click Browse and then select the file: c:\users\<yourname>\sample-1\sample-1-manifest.xml. Your add-in will now load on the Home tab, switch there, and press Show Taskpane.

This looks like a lot of work and I know for most of you that are like me, coming from a Visual Studio and/or VBA background, this is very alien. You might consider this a step backwards or it might seem like it is time to hang up the spurs. wlEmoticon-disappointedsmile.png But give it some time, especially if you are just getting into OfficeJS, it will grow on you. In the meantime, here are some of my other blog entries around this to help you:

Please let me know if you have questions or would like some help with any of this. What I hope to be able to do at some point is to add posts on:

  • Importing a Script Lab project into a Yo Office scaffold
  • A video on the steps outlined in this post. I have done videos for internal training at Microsoft before, but never on my own for my blog. So this will be new territory if I can get around to it.
  • Other samples posts to getting started with various projects.

If you have any ideas of what you would like to see, please let me know.