Originally posted on the DCS Innovation Labs Blog.
I've now written five posts in this series about modern frontend workflow in a .NET world without having really gone into any detail on the .NET part. That's going to change with this post. Having all of these new tools available to you has the potential to greatly improve the efficiency and enjoyability of your development process, as well as improving the maintainability of your code.
If you're a solo developer then all is well. You can start using this stuff right away without a hitch. Chances are though you are on a team with other developers. And chances are that these other developers have never heard of Sass or Gulp and probably aren't too interested in adding a ton of new tools they haven't heard of into their workflow. Your fellow developer doesn't want to have to run a ton of command line tools just to make sure the changes they made worked. They just want to run the debugger in Visual Studio and see the site boot up.
Introducing new tooling and processes to your stack means adding these things to your team's stack, and that's something that a lot of us often forget, myself included.
Luckily for us, the new and improved, open source friendly, semi-modern Microsoft has graced us with integration points for modern tooling in Visual Studio 2015. And these aren't just half-assed "you can press a button to run Gulp now" integration points. These allow you to truly make the new tooling you have introduced invisible to anybody but yourself, a goal that you should really reach for when trying to introduce something new to your team's stack.
In this post I'm going to go through:
- Integrating NPM with Visual Studio.
- Integrating Gulp with Visual Studio.
- Common problems and solutions.
This post assumes that you understand the basics of NPM, Gulp, Sass, Babel, and any other tool you may want to integrate into your frontend tool stack.
Earlier blog posts in this series cover:
These resources may be helpful to you if you're fresh to this whole modern frontend thing.
Please note that this tutorial targets Visual Studio 2015 only. If you were wise enough to avoid updating, you may have some luck trying out the task runner explorer extension for Visual Studio 2013. You would need to install this, as well as Node.js on any machine you wanted the integration to work on. I haven't tried this myself though so your mileage may vary.
For the best results here, make sure that the Visual Studio instances you are targeting (your machine and your coworkers' machines) are up to date. Specifically make sure that you have all of the core application updates and the "Microsoft ASP.NET and Web Tools" updates.
- Microsoft Visual Studio Professional 2015 Version 14.0.25425.01 Update 3
- ASP.NET and Web Tools 2015.1 14.1.20810.0
If you are running this or anything later then hopefully you won't run into any issues.
1) Integrating NPM with Visual Studio
The great thing about setting up this integration is that there really isn't anything that you have to do. If you were trying to set up your coworkers to use the command line version of these tools, you would have to install Node and all of the tools on all of their machines.
Visual Studio 2015 actually comes with its own distribution of Node.js pre-installed. This is both good and bad:
The good is that you won't have to install Node on all of your coworkers machines for them to use your shiny new tools. It's guaranteed to be installed and ready to use in Visual Studio (this installation of Node is not added to your path and won't be accessible from the command line).
The bad news is that the Node version included in Visual Studio is more than likely out of date. There is no way to directly update the version included and pointing Visual Studio to a different install is quite a chore that you don't want to have to administer on your entire team's dev machines. As of late, they have been doing a better job of keeping relatively modern (they are only one major version behind at the time of writing), but historically this has not been the case.
As of writing, my Visual Studio 2015 install comes with Node 5.4.1 which is modern enough to not cause any issues unless you want to write ECMAScript 2015 and have it interpret it without a transpiler, in which case you will need to be running Node > 6.
You can check your installed Visual Studio Node version at
C:\Program Files (x86)\Microsoft Visual Studio 14.0\Web\External\node.exe.
When a developer opens a project with a
package.json, Visual Studio will run
npm install automatically (though, it's taken up to 10 minutes before for me) to bring down your dependencies. It will not give you any indication of when this process will start, but once it has started, you can see the output from the command in the "Output" window if you set "Show output from" to "Bower/npm".
There's really nothing to it. Out of the box Visual Studio will integrate with NPM without any extra work from you.
2) Integrating Gulp with Visual Studio
Gulp integration is nearly as simple as NPM integration. We'll be setting this up in the "Task Runner Explorer" window. You'll probably need to add this by going to
View > Other Windows > Task Runner Explorer. In this window, you will see your Gulpfile, a list of the tasks in the Gulpfile, and a table of empty Bindings. In typical Visual Studio fashion, this window can take forever to load any data, so be patient and it should show up within a minute or two of opening your project.
Just like we would run Gulp in our command line to start developing, we need Visual Studio to start Gulp for us when we open a project. To do that, you just right click the name of the task you want to run and then select
Bindings > Project Open.
The task will now show up under the "Project Open" binding in the Task Runner Explorer window:
If you look at your
gulpfile.js, you will also see that a new line was added at the top that looks like:
/// <binding ProjectOpened='default' />. This line is what Visual Studio uses to know what task to run when the project is opened.
The next time you open the project, Visual Studio will run Gulp and you'll be able to see the output in the Task Runner Explorer window (though, you may have to wait a few minutes):
That's it! You have now successfully integrated your shiny new frontend workflow into Visual Studio! Your coworkers can continue on using Visual Studio without having to think about any of it and you get to reap all of the benefits of a more modern workflow.
3) Common problems and solutions
Gulp task works when run on the command line, fails in Visual Studio
As I mentioned earlier, the version of Node that ships with Visual Studio is probably out of date even if you are always applying updates. Some people, myself included tend to put off updating Visual Studio due to the fact that it takes half a day and is very likely to break something. Unfortunately, this can result in the Node version on your target machine being woefully out of date to the point of incompatibility (early releases of Visual Studio 2015 shipped with Node 0.12 for example). Since the Node ecosystem moves so fast, module vendors tend to drop support for old Node versions rather quickly.
There are a couple of ways to go about fixing this. Firstly, you can kindly ask the owner of the machine to update Visual Studio. If they are like me, they will probably say "hell no". When that fails, it's up to you to make your build script compatible. This involves debugging the error that occurred, finding the problem module, and downgrade it by explicitly setting a compatible version in
package.json until you are running a version compatible with the version of Node running in your target Visual Studio 2015 instance. I had to do this often in the early days of Visual Studio 2015 but it's rarely an issue now.
The Gulp tasks set up in the Task Runner Explorer aren't there the next time the project is opened
There are a couple of things that could cause this.
The likely case is that Visual Studio just hasn't loaded everything yet. Visual Studio is slow, give it a couple of minutes and things will probably show up.
Every once in a while, Visual Studio just won't bother loading the gulp tasks. There is a refresh button in the Task Runner Explorer window that sometimes fixes this, and a restart of Visual Studio is a solid backup plan.
One other possible issue is that a code formatter such as ReSharper broke the binding statement at the top of your
/// <binding ProjectOpened='default' /> into
// / <binding ProjectOpened='default' />.
Dependency install fails in Visual Studio (missing binding error)
When you install one of these native dependencies with NPM, it is actually compiled for your system configuration. If you don't have a Node install outside of Visual Studio (as your coworkers probably don't), you shouldn't run into any problems.
The issues arise when you install a native dependency using your global Node install, and try to install that dependency again using Visual Studio. For some reason that I can't comprehend, Visual Studio uses the 32 bit version of Node and you are more than likely using the 64 bit version of Node globally.
The best fix for this is to use the global Node install instead of the one in Visual Studio. You can change the version Visual Studio points to by going to
Tools > Options > Projects and Solutions > External Web Tools, adding an entry for your Node install (mine is
C:/Program Files/nodejs), and moving that to the top of the list.
After restarting Visual Studio you should now be running the version of Node that you have installed globally on your machine instead of the one that ships with Visual Studio.
Wrapping things up
I'd be a bit of a hypocrite if I wrote this series and didn't use these practices and this tooling myself. I'm happy to say though that not a day goes by where I don't make use of all of it. It's become so critical to my workflow that I go through these steps for every single project I work on no matter how small. Having strong integrations with Visual Studio allows for my coworkers to not be interrupted and also allows me the freedom to use other development tools since the command line tools for Gulp, Sass, Babel and the like are still available to me.
I hope that you were able to get some useful information out of this series and will consider adopting some of these tools and practices for yourself. It can definitely seem daunting from the outset getting all of this tooling set up, but the benefits will become obvious pretty quickly once you start developing with them and the boilerplate is generic enough that you can reuse most of it between projects, reducing set up time drastically.