JScript IntelliSense FAQ
I've been reading through the 70 or so comments on our last 2 jQuery posts. There have been a lot of great questions. Apologies for not being able to answer them sooner (I was busy preparing for Dev Connections). Instead of answering them inline with the comments, I'll try to paraphrase the popular issues here and answer them centrally.
1. I have a ton of Content Pages, do I need to put script references for IntelliSense in each one?
No, you do not need to repeat the script references on each content page. Visual Studio 2008 will auto-detect the presence of a master page and scan for references in that file. Thus, placing references in the master page is all you need to do.
2. I put a vsdoc reference in the Master Page, why is IntelliSense not working in a User Control?
User Controls do not specify a master page. Thus, there is no way for Visual Studio to guess which master page the user control will end up on. Generally, we simply can't predict which file a user control will end up on. Thus, we are unable to provide IntelliSense.
"Shail" provided the best suggestion, which is just to include a list of script references you want on your user control, then wrap those controls with a "<% if (false) ... %>" to make sure you don't redundantly include scripts at runtime.
I can see a centralized list of references helping this scenario, which leads into the next question...
3. Is there a way to specify a centralized list of references for IntelliSense?
Unfortunately, not right now. Short of writing your own ScriptManager or similar code, there's no "built-in" way to specify a centralized list of references for IntelliSense (or for the runtime). There's no web.config location for this (as "CurlyFro" asked) nor is there a Tools Options list you can set.
However, there is a fairly useful trick that is worth mentioning. You can create a JS file with no code (let's call it "list.js") that contains solely a list of commonly used references (the XML comment type) at the top. Instead of putting a list of individual references on top of each JS file, you can simply include just a reference to "list.js". The meta-point here is that references originating from a script (not HTML/ASPX) file are transitive. If A references B, and B references C and D... A effectively references B,C, and D. Having the centralized file saves you from updating 100's of files when you add one more script to your project. As mentioned above, Master Pages serve as a unified place to put scripts for HTML/ASPX pages.
"Peter" suggested there was a similar issue with CSS files. Given the feedback, this is something we can definitely take into consideration. I'm curious: how many files you are typically including into your pages? Will the workarounds provided suffice?
4. Which URL-path types does IntelliSense recognize?
I saw a lot of questions/feedback/comments regarding paths and URLs. I'd like to clarify what is supported and not supported by Visual Studio JScript IntelliSense then ask for feedback:
- File-Relative Paths - These are paths of the form "../../folder/file", and is calculated from the current file(http://site/application/folder/file). Visual Studio, ASP.NET Web Forms, and ASP.NET MVC all support this type of path and resolve these correctly. The challenge, however, is with master pages. This type of path is not re-based when a master page is merged with a content page. Thus if you content pages are at varying folder depths, your paths will be broken. Incidentally, ASP.NET MVC folder paths tend to be exactly two levels deep because of the conventional MVC dictated folder structure of "Views/ControllerName". Because of this, I would recommend this type of path for MVC, but not for Web Forms.
- App-Relative Paths - These are paths of the form "~/folder/file", and is calculated from the base of your application (http://site/application/folder/file). Visual Studio and ASP.NET Web Forms both support this type of path provided you specify it inside a Script Manager (and a few other runat=server controls). Since ASP.NET MVC is not normally used with Script Manager controls, app-relative paths will not work with MVC. By the way, this type of syntax is not supported inside plain <script> tags regardless of technology. App-relative paths are re-based when a master page is merged with a content page. Thus it is not broken by content pages at varying folder depths. Thus I would recommend this approach for Web Forms. The Script Manager normally injects MS AJAX into your rendered page. What if you are not using MS AJAX? The Script Manager can be modified to not to inject MS AJAX.
- Site-Relative Paths - These are paths of the form "/folder/file", and is calculated from the base of your site (http://site/application/folder/file). This approach is supported by ASP.NET Web Forms and ASP.NET MVC. However, it is not supported by Visual Studio. The reason is because Visual Studio does not always know the final deployed location of your site and thus the path resolution cannot be guaranteed. Given that quite we've seen few folks are using site-relative paths, we could consider making an assumption just resolving this type of path to the root of the project. Given the risk that you may think your site is working when it's really not, I wanted to see how many people were supportive of this.
- Absolute Paths - Obviously, by absolute, I mean paths of the form "http://site/etc". Note, as of Service Pack 1, we will now resolve this type of path... fetching the file over the network if necessary.
In a nutshell, I'm recommending ../../folder/file for MVC and ~/folder/file for Web Forms. Also, we can resolve site-relative paths to the project root for if there's enough demand.
5. How do I get IntelliSense to understand "google.load()"?
The google API has a dynamic way of including script files via the "load" function. Unfortunately, IntelliSense will not be able to understand that this function brings in new scripts. My recommendation here would be to include your file statically via a <script> tag. You can wrap it a "<% if (false) ... %>" if you won't want to double-include the script at runtime.
6. I'm getting a "childNodes is null" error, what is it and what do I do?
If you're using jQuery, the "childNodes" error is indicative of IntelliSense not happy with a particular plug-in. Note, the error will misleadingly point to the jquery-1.2.6-vsdoc.js file. The cascading set of errors lands in the core jQuery code, however it originates from the plug-in. For example, the jQuery UI DatePicker is one of the plug-ins that will show this error.
Generally for any JavaScript library, a "childNodes" error is caused by libraries that try to create DOM elements on parse rather than slightly later on load. DOM element creation is not supported at design-time (IntelliSense-time as I call it) and thus you get a null reference exception when you try to call "childNodes" on the element. Note, this is a perfectly acceptable pattern... it's our fault that it causes an error. In fact, we've made some major architectural changes to accommodate this in Visual Studio 2010 but I'll save that for another post.
We will try to work with library owners to product VSDOC files for their libraries in the future. For now, the best option is to hide the file from IntelliSense... see question #8.
7. What makes a jQuery plug-in incompatible or compatible for IntelliSense?
There's no hard and fast rule for compatibility with IntelliSense. However, from my experience, if a plug-in is going be incompatible, it's going to be because it tries to create and modify a DOM element before the document is ready. Please see the previous question for more details. If you frequently see another type of issue, please let us know (via a comment on this post or you can email me... address at the bottom) and we'll be sure to investigate to provide an explanation.
8. How do I hide a file from IntelliSense?
"Igor" came up with a clever solution outside the box of what the "vsdoc" feature was originally intended for. =) However, I think it's great and worth repeating. You simply create a empty -vsdoc.js file for the offending library... effectively making Visual Studio skip the problematic ones. Of course this means you get less IntelliSense, but it's better than none.
9. Can you add support to recognize more file extensions?
I saw a request from "Jerry" to recognize the "dash debug" convention. I also saw some folks mistakenly use a "dot vsdoc" naming scheme. Note vsdoc is supposed to be a "dash vsdoc" rather than "dot". Of course there's also the "dot min" extension for compressed files. We can definitely add support for more file extensions in a future release. Feedback for which ones are the most important would be helpful in making sure we support the right set.
10. In Visual Studio 2005 I am getting no IntelliSense, what do I need to do?
You'll need to upgrade to Visual Studio 2008. I hate to pull the "buy a new version" card, but JScript IntelliSense was a fairly involved code change and it would be non-trivial to back-port it to Visual Studio 2005.
11. Is there a way to get around closing and reopening an file to get Visual Studio to update IntelliSense?
Yes. Please use Ctrl + Shift + J to manually force JScript IntelliSense to update. For menu-lovers, this command can be found under Edit, IntelliSense, Update JScript IntelliSense.
Summary
I hope this FAQ clears up the common points of confusion. I saw a few comments akin to "because of ____, this feature is useless to me." As harsh as they sound, those comments are the most useful to us. If there's something in your way, feel free to email me at jking at microsoft dot com. I'd like to see if there's something we can figure out for you. Thanks for reading!
Jeff King
Program Manager
Visual Studio Web Tools
