Leveraging Visual Studio JavaScript IntelliSense. Part 1

One of the most useful features of Visual Studio 2008 and Visual Studio 2010 is JavaScript IntelliSense that allows developers to write JavaScript code faster, with fewer errors and reduce learning time of some JavaScript frameworks. Many developers already enjoy its power when coding JavaScript with Microsoft ASP.NET Ajax framework and jQuery. However many developers are still not familiar with that tool and even less developers realize that it can also be used with their own code.

As convenient and powerful the JavaScript IntelliSense is as it is not intuitive to get started with mainly because of its lack of well-organized documentation and non-intuitive error diagnostics. Another obstacle is that it does not support its own XML code comments that makes it hard to use to the full extent without learning and memorizing first.

This article aims to provide with a quick reference the most useful features of the JavaScript IntelliSense to help make it an every-day tool for JavaScript developers.

In short words, JavaScript IntelliSense provides two main features:

1. It enables documentation and syntax support while coding for the core JavaScript elements and third-party JavaScript libraries;
2. It allows adding documentation and syntax support to the code being developed so other developers can use it.

In this post, I cover the first feature.

Enable JavaScript IntelliSense for Third Party JavaScript Libraries

The IntelliSense support for the core JavaScript syntax is enabled by default. In order to enable IntelliSense for third party code, one needs to satisfy the following requirements:

1. Reference a third party JavaScript file in your code, and
2. Make sure the third party JavaScript includes Visual Studio XML code comments

The second requirement is in fact optional because JavaScript IntelliSense will work even without XML comments but will provide less information, so it actually pays off checking out before choosing a third-party JavaScript library whether it has a VS IntelliSense support. Many of the most popular JavaScript libraries such as ASP.NET Ajax, jQuery, Bing Maps, etc. do support VS IntelliSense.

Referencing Another JavaScript Library in your JavaScript Code

Simply use a reference directive in your JavaScript code. There are a few flavors of that directive depending on the location of a third party JavaScript code. A reference directive supports file-based, assembly-based, service-based, or a page-based script references. Below are the examples illustrating those scenarios:

<script type="syntaxhighlighter" class="brush: javascript">
// Reference a file-based JavaScript
///<reference path=""file-path-to/script-name.js"" />

// Reference a service-based JavaScript
/// <reference path=""url-path-to/wcf-service.svc"" />
/// <reference path=""url-path-to/asmx-service.asmx"" />

// Reference a web page-based JavaScript
/// <reference path=""url-path-to/page-name.aspx"" />

// Reference an embedded resource JavaScript
/// <reference name=""resource-name"" assembly=""assembly-name"" />
</script>

A -path-to portion above can be both a file path to a local or network location or a web URL to both intranet and Internet resources. In the latter case, keep in mind that the Internet resource will be accessed every time Visual Studio opens a JavaScript file with a reference so it is better to cache it locally which is also much safer. In case of a service-based reference, the actual URL Visual Studio has to access will be 'service-url/jsdebug' or 'service-url/js' based on the solution configuration, therefore make sure that the project a service belongs to compiles without errors.

It is not necessary to reference an original JavaScript code itself (for example, if it's hosted somewhere outside of your development environment) if there is a VSDOC file provided as it is with jQuery or Bing Maps libraries for example.

A VSDOC file is a JavaScript file that only includes objects definitions and functions signatures with XML comments without actual code and is a preferred way to add extensive documentation to a JavaScript library without modifying the original JavaScript code. In case there are no XML comments in the code nor VSDOC file is available, simply reference an original JavaScript file and Visual Studio will parse it and provide you with the best possible IntelliSense help. If you use Microsoft ASP.NET Ajax framework, add the following reference to the top of your JavaScript code:

<script type="syntaxhighlighter" class="brush: javascript">
// Reference Microsoft ASP.NET Ajax framework
/// <reference name=""MicrosoftAjax.js"" />
</script>

You may have noticed that this is a reference to an embedded resource but without assembly name. Such a reference only works for so called well-known assemblies that are listed in a web.config file such as in this case a System.Web.Extensions. If you use a JavaScript library that comes in the form of a DLL containing multiple JavaScript, you may consider listing it in a web.config file and save on assembly name in multiple reference directives.

IntelliSense Rules

The JavaScript IntelliSense behavior is determined by the following rules:

1. Private class members defined inside a class constructor are not visible in IntelliSense. If you need to have IntelliSense support for private members, define public getter (get_...) and/or setter (set_...) methods for them with XML comments.
2. Class methods with names beginning with underscore are considered private and not visible even if they have XML comments.
3. Public class methods can be defined in a class prototype or in standalone code.
4. If XML comments are not provided, only a method name and a list of arguments are displayed.

IntelliSense Errors

If you don't see IntelliSense support for a JavaScript library even though you have added all the references, check out the Visual Studio Errors tab. If IntelliSense cannot load a referenced file, it will display a message like 'Could not load ...' in the Errors tab. The most common reasons for IntelliSense not being able to a load a referenced file are:

• File is not found at the location or location/file name is invalid. If the file is located on the Internet or a network share, there may be a problem accessing those locations from your machine.
• A referenced JavaScript file contains errors. If IntelliSense cannot successfully parse the file, it will not load it.
• If a referenced JavaScript is an embedded resource from one of the solution's projects, the project is not compiled for some reason and the DLL is not found.

This is all for the first part. In the next post, I will explain how to use XML comments in your own JavaScript code to IntelliSense-enable it. If you find something missing or incorrect in this post or have suggestions regarding what else to cover, please write a comment and I will get back to you ASAP.

More to Read

• JavaScript IntelliSense overview on MSDN
• Scott Guthrie about JavaScript IntelliSense
• JScript IntelliSense Reference on WebDevTools Blog