The Visual Studio Blog : extensibility

Introducing the Microsoft “Roslyn” CTP

Visual Studio Blog — Wed, 19 Oct 2011 12:30:00 GMT

Today we are releasing the first Community Technology Preview of the Roslyn Project!

What is Roslyn?

In the past, our compilers have acted as black boxes – you put source text in and out the other end comes an assembly. All of that rich knowledge and information that the compiler produces is thrown away and unavailable for anyone else to use.

As Soma mentions in his blog, a part of the Visual Studio languages team is working on a project called Roslyn with a goal to rewrite the C# and VB compilers and language services in managed code. With a clean, modern, managed codebase our team can be more productive, innovate faster, and deliver more features sooner and with better quality.

More importantly, we are opening up the C# and Visual Basic compilers and exposing all that rich information and code analysis to be available for your use. We expose a public API surface and provide extension points in the C# and VB language services.

This opens up new opportunities for VS extenders to write powerful refactorings and language analysis tools, as well as allow anyone to incorporate our parsers, semantic engines, code generators and scripting in their own applications.

Download the October 2011 CTP

The CTP and supporting materials can be downloaded from:

http://msdn.com/roslyn

The main goal of this early preview is to gather feedback on the API design and to introduce the C# Interactive window (also known as REPL, or Read-Eval-Print-Loop).

This first CTP is intended for preview-use only and does not allow redistribution of the Roslyn components or allow use in a production environment.

The CTP installs on Visual Studio 2010 SP1. It also requires the Visual Studio 2010 SP1 SDK.

Getting Started

After the installation succeeds, the best place to start is to open Start Menu -> Microsoft Codename Roslyn CTP -> Getting Started.

To get started, the “Roslyn Project Overview” document gives a look at the compiler API – how to work with syntax and semantics of your program. Several walkthrough documents are also included to provide a deep dive into various aspects of the Roslyn APIs.

The CTP ships with quite a few samples for Visual Studio Extensions, compiler API, code issues, refactorings and so on. Most of the samples are provided for both C# and Visual Basic. You can open the sample source code from the Getting Started page.

We also install several new project templates available in the New Project dialog:

These templates will help you to get started on a new Visual Studio extension that uses Roslyn.

Reference Assemblies

The Roslyn assemblies are also installed in the GAC. Switch to the Full Profile (instead of the Client Profile) to be able to also reference the Services assemblies (which contain the IDE support).

C# Interactive window

You can invoke the C# Interactive window from View -> Other Windows -> C# Interactive Window. The Interactive window is powered by the new C# language service. The architecture of Roslyn is flexible enough to allow many of the IDE features such as IntelliSense and refactorings to work the same in a normal editor and in the Interactive window.

At this time, the Interactive window is only available for C#. We’re working hard on providing the VB Interactive at a future time.

C# Script File (.csx) Editing Support

The CTP introduces a concept of a C# Script File. You can create a .csx file through File -> New File (or also use any other editor such as notepad):

You can run scripts using the new rcsi.exe, which installs into %ProgramFiles(x86)%\Microsoft Codename Roslyn CTP\Binaries\rcsi.exe. You can add rcsi.exe to the path and then type rcsi <scriptfilename>.csx.

You can also copy chunks of code from a script file and send them to the C# Interactive Window (using the right-click context menu or a keyboard shortcut).

The editor for the script files is also powered by the new language services. Hence it is important to keep in mind that .csx scripts will only support the part of the language already implemented in the Roslyn compilers. For more details, see the "Introduction to Scripting" walkthrough.

Quick sample of the Roslyn API

Here’s a sample of compiling and executing a small program using the Roslyn API.

using Roslyn.Compilers;
using Roslyn.Compilers.CSharp;

...

var text = @"class Calc { public static object Eval() { return 42; } }";
 
var tree = SyntaxTree.ParseCompilationUnit(text);
var compilation = Compilation.Create(
    "calc.dll",
    options: new CompilationOptions(assemblyKind: AssemblyKind.DynamicallyLinkedLibrary),
    syntaxTrees: new[] { tree },
    references: new[] { new AssemblyFileReference(typeof(object).Assembly.Location) });
 
Assembly compiledAssembly;
using (var stream = new MemoryStream())
{
    EmitResult compileResult = compilation.Emit(stream);
    compiledAssembly = Assembly.Load(stream.GetBuffer());
}
 
Type calc = compiledAssembly.GetType("Calc");
MethodInfo eval = calc.GetMethod("Eval");
string answer = eval.Invoke(null, null).ToString();
 
Assert.AreEqual("42", answer);

Note: At this stage, only a subset of the language features has been implemented in the current CTP. We’re moving forward at a fast pace, but features such as Linq query expressions, attributes, events, dynamic, async are not yet implemented. To see a full list of non-implemented language features, see the Roslyn forums.

Although not all the language features are supported, the shape of the public API is mostly complete, so we encourage you to write extensions and tools against the Syntax, Symbols, and Flow and Region Analysis APIs.

We’re very excited to get an early preview of this technology in your hands and we welcome your feedback, ideas and suggestions. Use the forums to ask questions and provide feedback, Microsoft Connect to log bugs and suggestions, and use the #RoslynCTP hashtag on Twitter.

Thanks,

Kirill Osenkov

QA (Roslyn Services Team)

Blog: http://blogs.msdn.com/b/kirillosenkov

Twitter: @KirillOsenkov

Extension Analyzer V3

Visual Studio Blog — Fri, 01 Oct 2010 08:00:00 GMT

Extension Analyzer is an Extension to Visual Studio 2010 that allows browsing several extensibility entities inside of Visual Studio. It also allows diagnosing several common errors loading extensions by reporting information from logging services inside Visual Studio.

The Extensibility team in Visual Studio has recently added several exciting features to the Extension Analyzer tool. In addition to browsing through Visual Studio Packages and MEF Extensions, it is now possible to browse through the collection of VSIX extensions and PkgDef files installed on the machine. The tool scans the contents of the VSIX extensions and PkgDef files and establishes relationships between the VS Packages, VSIX extensions, PkgDef files and MEF Components. These relationships allow navigation between the different entities.

The latest version of the tool can be downloaded from the Visual Studio Gallery. This post describes in detail the new features added to Extension Analyzer.

Extension Browser VSIX Tab

The new VSIX Tab displays information about installed VSIX Extensions. Each VSIX Extension has a unique VSIX Identifier plus other information about the Extension. When a row is selected in the grid, the Properties window updates with information about the selected VSIX.
The VSIX Tab has a checkbox to toggle showing System Components or not. This allows reducing the amount of data the user sees, which typically does not need to browse through System Components. A System Component is a VSIX whose manifest has the SystemComponent property set.

It is also possible to navigate back and forth between the VSIX Tab to see the definitions of VSIX units and the Log Viewer to see log events related to a specific VSIX. To collect events in the Log Viewer, remember to start Visual Studio with the /log switch.

Selecting the context menu on a VSIX row includes the following actions:

Navigate to Log entries for selected VSIX.
Open VSIX Manifest in Visual Studio editor as XML.
Open VSIX folder.

Extension Browser PkgDef Files Tab

The PkgDef Files Tab displays information about PkgDef files available to Visual Studio. Each row shows the short name of a PkgDef file, its path and if the PkgDef file is a System Component or not. This tab is also fully integrated with the Properties Window in Visual Studio.

The value for System Component property is inherited from the VSIX that contains the PkgDef, if any. If the PkgDef did not come from a VSIX, the value for System Component is undefined (blank), because there is no exact way to determine if the PkgDef is a System Component or not. The PkgDef Files Tab contains a checkbox to toggle showing System Components or not. This is again to reduce the amount of relevant data the user sees.

If a PkgDef file was deployed through a VSIX Extension, the value for the property VSIX Identifier contains the identifier of the corresponding VSIX. This value can be used to navigate to the corresponding VSIX Extension in the VSIX Tab and observe several other properties of that VSIX.

Several PkgDef files (specially System Component ones) are not deployed through VSIX and their VSIX Identifier property will be empty. It is possible now to filter out columns with empty values by entering a filter like this in the Filter control of the tab:
-VSIXIdentifier=””

Notice that the “-“ prefix filters out the rows with empty values. Without the “-“ or with a “+” prefix will include the rows with empty values.

Similar to VSIX, it is also possible to navigate back and forth between the PkgDef Files Tab to see the definitions of PkgDef files and the Log Viewer to see log events related to a specific PkgDef file.

Selecting the context menu on a PkgDef file row includes the following actions:

Navigate to Log entries for selected PkgDef.
Navigate to VSIX that installed selected PkgDef (if available).
Open PkgDef file in Visual Studio editor as XML.
Open PkgDef file folder.

Updates to VS Packages Tab

The VS Packages Tab of the Extension Browser has been updated with a couple of features. There is now a new PkgDef File Identifier column that links a VS Package to the PkgDef, if any, that registers the package. The association between VS Packages and PkgDef files is done using the Codebase or Assembly properties for Managed packages or the Path property for Native packages.

Several VS Packages internal to Visual Studio are registered directly during Setup and do not have PkgDef files associated with them. However, most VS Packages created by external users using Visual Studio 2010 will have PkgDef files and VSIX deployable units associated with them.

There is also a new VSIX Identifier column that links a VS Package to the VSIX that deployed the package. These associations are computed using the PkgDef files that registered the VS Packages. Basically, a VSIX is associated with a VS Package if the VSIX contains a PkgDef file that registers the package.

The Is System Component column is now computed from knowing if a VS Package is internal to Visual Studio or if the VSIX of the VS Package is marked as a System Component.

Selecting the context menu on a VS Package row includes the following actions:

Navigate to VSIX that installed the selected VS Package (if available).
Navigate to PkgDef file that registered the selected VS Package (if available).
Open VS Package file folder.

Updates to MEF Components Tab

The MEF Components Tab of the Extension Browser has been updated with a couple of features as well. First, there is a new VSIX Identifier property for each MEF entity that allows correlating the MEF entity with a VSIX Extension that deployed the entity, if any. It is now possible to navigate to the VSIX Tab from a given MEF entity.

One other feature added is to include a System Component column for each MEF entity. The value of this property is inherited from the VSIX that deployed the entity and allows filtering System Components using the Show System Component checkbox. This again substantially reduces the amount of data that external users see, showing only components that are more relevant and not internal to Visual Studio.

The following context menus were added to MEF entities:

Navigate to VSIX that installed the selected MEF entity (if available).
Open MEF entity folder.

We hope you find the new features in this tool useful.

Mynor Ivan Muralles, Software Design Engineer, Visual Studio Team

15 minute blog post: PNG files in Packages

Visual Studio Blog — Sun, 27 Jun 2010 23:00:00 GMT

Recently I’ve been helping plan the next version of Visual Studio. It’s way too early to be talking about specifics, but one topic came up this week that I have to share.

Package Authoring

As some of you may have noticed, many of the regular posters here have been busy writing extensions for the Visual Studio Gallery, some of which have been featured on this blog. You too can create extensions for Visual Studio 2010 using the Visual Studio SDK. If you’ve ever created a package with menu items (commands) using the SDK you’ll notice that the default wizard-generated package contains a sample image strip that looks like this:

These are the little 16x16 icons that appear on menu items and toolbar buttons. It’s just placeholder artwork for various commands that you might want to implement in your new package. You’re supposed to edit the image to add your own artwork. However, the image is in a strange format: It’s a 32 bits per pixel image with a .BMP extension (the filename is “Images_32bit.bmp”). If you try and edit it in Visual Studio, you’ll find that the built-in image editor doesn’t understand the format. The interesting thing is that this image contains a full 8-bit alpha channel. We’ve come across alpha channels before in the discussion of the Splash Screen and another area where Visual Studio supports full alpha is on menus and toolbars. Unfortunately, the .BMP file specification doesn’t officially support this 32bpp ARGB format and many applications will either refuse to recognize it or will drop the alpha channel on saving.

PNG to the rescue

Since this 32-bit ARGB format is so hard to work with, I suggested to the planning group that we add support for .PNG files to the VSCT compiler (the compiler which reads your package’s command definitions, including these bitmap strips, and produces binary resources). The owner of the VSCT compiler replied and said that there was no need because it already did support .PNG – in fact, it accepts any format that System.Drawing.Image.FromFile supports. Sure enough, after a quick experiment, I confirmed that is true and, indeed, MSDN already has the appropriate note if you know where to look. Somehow, I had assumed that, since the wizard spat out that annoying 32-bit BMP file, that was the only file format supported and, moreover, I don’t think I’ve ever seen anyone use PNG files internally – and I’ve seen a lot of VSCT files in my travails/travels.

Conclusion

So, there you have it. Use .PNG files for your bitmap strips. PNG has, in recent years, become the de-facto standard for images with full-transparency and lossless compression and there are many free image editing applications which support it.

P.S. I wasn’t the first to spot this, and, since I started writing this article and doing a little research, I found a few examples of using .PNG files in VSCT on codeplex. Still I think this little known fact deserves some more visibility. Perhaps in the next version of the SDK we can change the template to emit PNG files by default.

Paul Harrington – Principal Developer, Visual Studio Platform Team.
Biography: Paul has worked on every version of Visual Studio .Net to date. Prior to joining the Visual Studio team in 2000, Paul spent six years working on mapping and trip planning software for what is today known as Bing Maps. For Visual Studio 2010, Paul was the architect for the move to WPF. Paul holds a master’s degree from the University of Cambridge, England and lives with his wife and two cats in Seattle, Washington.

Document Well 2010 Plus

Visual Studio Blog — Wed, 09 Jun 2010 23:30:00 GMT

[Update 6/21/2010]: Please go to this blog post where I describe even more configuration options that are available for this extension.
[Update 7/20/2010]: Updated changes made for version 10.0.10710.22 of the Pro Power Tools. Please take a look at the changelog.

For some time, the behavior of tabs in Visual Studio's document well has been a source of frustration for some users. Whenever behavior is modified, some users are happy with the changes, while others are not. In an attempt to alleviate this problem I have created this extension, which provides configurable behavior for document tabs. It is available in the Visual Studio Gallery, as part of the Visual Studio 2010 Pro Power Tools. All configuration options are accessible by selecting Tools/Options.../Pro Power Tools/Document Tab Well. I encourage you to experiment with all available options, so you can find what works best for you.

Configuration Presets

This extension provides a fairly large feature list. To provide examples of what is possible, as well as a starting point for users to build their own configurations, we include several different presets that showcase the features available. They are the following:

Visual Studio 2008

This preset mimics the behavior of Visual Studio 2008: The close button will be located in the document well, instead of in each individual tab.

Visual Studio 2010

This preset mimics the behavior of Visual Studio 2010.

Web Browser: Scrollable tab well

This preset mimics the behavior of commonly used web browsers. Tabs will be scrollable, icons and a close button will appear in each tab, and new tabs will be inserted on the right by default.

Scrollable Tab Well: Sorted by project

This preset will have scrollable tabs, sort them and color them according to the project they belong to. This is useful if you regularly work in a solution with several projects.

Vertical Tab Well: Color coded and sorted by project

This preset is similar to the previous one, but additionally tabs are shown vertically. This allows showing more tabs than is normally possible when laid out horizontally.

Dynamic Tab Well: Removes tabs based on usage

This preset showcases a modification to standard Visual Studio 2010 behavior. Instead of hiding tabs that are on the right of the tab well when there is no more space available for them, it will hide the least recently used tab.

Feature List

At the moment the extension provides the following configurable behavior features:

Tab Well UI
Tab Behavior
Sorting
Tab UI
- Color tabs according to their project or according to regular expressions
- Miscellaneous options that modify tab UI
  - Show document/toolwindow icon in tab
  - Show close button in tab
  - Show pin button in unpinned tabs
  - Modify dirty indicator style
  - Modify minimum and maximum tab size
Useful Commands
- Close all but pinned

Tab Well UI

Scrollable Tabs

By default, VS 2010 hides tabs when there is not enough space to display all those that are open. When a hidden tab needs to be visible, it is inserted at the beginning or the end of the tab well, according to preferences.

We provide the ability to instead scroll tabs, thus avoiding the need to change their position in the tab well whenever they become visible:

Note the arrow button on the right of the tab well. Clicking it will scroll the tabs one at a time. Keeping it pressed will continually scroll tabs until it is released.

The selected file has been scrolled to the left and is now not visible in the document well. In order to find out now what is the selected tab, we can simply press the document well drop down button:

Note that the selected tab appears in bold, and all hidden tabs appear in italics. Note that in this example the files in the drop down appear in visual order, instead of alphabetically sorted, which is the default behavior of VS 2010. This is configurable through the sorting options.

Vertical Tabs

If you work with many open documents at once, you might find that showing tabs vertically allows you to have a larger number of tabs visible. You will be able to open more documents before any of them needs to be hidden.

Please note that you cannot reorder tabs when displayed vertically. My personal recommendation would be to keep them sorted alphabetically so they are easy to find.

Pinned Tabs

While the objective of LRU mode is to keep your most recently used tabs available, you might want to always have some documents easily accessible, no matter how often you access them. By pinning a tab, it will always be readily available.

Let's say you have 4 files open in your project: Class1.cs, Class2.cs, Class3.cs and Program.cs. You might have something like the following image:

Notice that only 3 tabs are visible, as there is no space to show all of them. If you are mainly working on Program.cs, but have to constantly switch to the other tabs, there is a chance that the tab you mainly work on might become hidden. You will probably want to have this document always available. If a tab has to be hidden, it should be any of the others. When you hover the mouse pointer over a tab, you will notice that a pin button becomes visible. Pressing this button will pin the tab. Alternatively, press the right mouse button over the tab, in order to bring up its context menu, and select "Pin Tab" (This command is also available through the menu option Window/Pin Tab):

After selecting this command, the selected tab will become pinned. Notice that the tab has been brought to the front of the document well, and that it has a pin button to indicate its status. You can press this button to unpin the tab, or alternatively use either the tab's context menu or the Window/Pin Tab menu option:

An important note: At the moment you cannot reorder pinned tabs. They will appear in the same order they had in the regular tab strip. If you attempt to move a pinned tab it will become a floating window.

Show Pinned Tabs in a Separate Row/Column

If you have several tabs pinned, you might soon run out of space in the document well to display unpinned tabs. The extension also provides an option that will use a separate row for showing only pinned tabs. If this option is turned on, our previous example will appear as follows:

Notice that now all our tabs are visible.

Show close button in tab well

This setting brings back the close button that was present in the document well in Visual Studio 2008. It will close the currently active tab in the document well.

Tab Behavior

Remove Tabs By Usage Order

This behavior extends the default VS 2010 fixed document well. Tabs that do not fit in the available space will be hidden, but instead of hiding the tab on the right or the left of the tab well (according to preferences), the tab that will be hidden is the least recently used tab. This makes commonly used tabs available.

In the following example we have 4 tabs open. The order in which they were shown is Class1.cs, Class2.cs, Class3.cs and Class4.cs.

When the space available is reduced, the least recently used tab (Class1.cs) is hidden. If we show the tab well drop down, we can confirm that Class3.cs has been hidden but still remains between Class2.cs and Class4.cs:

If we select Class1.cs from the drop down to make it visible, the tab that will be now hidden is Class2.cs:

Insert Tabs At Right

By default Visual Studio 2010 inserts new tabs to the left of the document well. Turning on this option will insert new tabs to the right instead. This option will have no effect if alphabetical sorting is turned on.

Please note this option is the same option that is present in Tools/Options.../Environment/Documents. It is presented in our options dialog as a convenience to our users.

Sorting

Sort Tabs By Project

Documents that belong to the same project will be grouped together in the tab well. When alphabetical sorting is on, tabs will be sorted by project first and then by name. Having this option turned on and alphabetical sort off will allow tab reordering, but only within the project group.

Sort Tabs Alphabetically

Whenever a tab is added to the tab well it will be inserted in its corresponding alphabetically ordered position. Naturally, this precludes tab reordering.

Sort Drop Down Alphabetically

Default Visual Studio 2010 behavior is to display the document well drop down in alphabetical order. This option allows the dropdown to appear in the same order in which the tabs are laid out. This is particularly useful when Removal by Usage Order is turned on.

Tab UI

Coloring Tabs

The extension provides the ability to set custom colors for document well tabs. Tabs can be colored according to:

Regular Expressions
Project they belong to

Select Tools/Options.../Environment/Document Tab Behavior/Color Coding to configure the colors that will be used for tabs according to the project they belong to, as well as regular expressions that will be used to color tabs. Matching for these regular expressions is case-insensitive.

We provide by default 15 colors for coloring tabs according to their project. If your solution has more than 15 projects, colors will be reused. You can always add more custom colors if you need to.

In the following example a red color is used for tabs that match ".*\.xaml$", a blue color is used for tabs that match ".*\[design\].*", and a green color is used for tabs that match ".*\.txt$":

In the following example we can see a solution that contains 3 projects, with coloring according to project turned on. This feature is specially useful when used with "sort tabs by project":

Miscellaneous Tab UI Options

The extension provides the following options for configuring the UI of individual tabs:

Close button presence - Allows to configure whether the Close button appears in the tab or not.
Dirty Indicator style - Allows to use a red dot or a disk icon as alternatives to the old text asterisk to indicate that a file is dirty.
Show document/toolwindow icon: If selected, the icon corresponding to the current open document or toolwindow will be shown in the tab.
Show pin button in unpinned tabs - When unchecked, will hide the pin button that appears on hover in unpinned tabs.
Set minimum and maximum tab sizes - If you think tabs in VS are too big or too small, you can configure their maximum and minimum sizes here. Try making the minimum size the same as the maximum size, and you will have evenly spaced tabs:

Useful Commands

Close all but pinned - This command (accessible through a document tab's context menu) will close all document tabs that are not currently pinned.

Changelog

Version 10.0.10710.22

Added configuration option in UI for showing/hiding pin button in unpinned tabs
Made selected tab use a color gradient by default in order to make it more distinguishable when using custom colors
Added configurable colors for text in selected and unselected tabs, as in some instances the text was not readable
Added command: "Close all but pinned".

Tell Us What You Think

Please be sure to tell us your opinion about this extension and the features provided. There is a chance that the most-liked and/or useful features will be included in the next version of Visual Studio, and of course we would like to improve on any feature that our users don't find useful. You will find a hyperlink in our options dialog which you can use to provide us with feedback. You can also add comments to this post directly, add/contribute to a discussion in the Visual Studio Gallery page for the Visual Studio 2010 Pro Power Tools, or send us feedback directly at docwell2010plus [at] microsoft.com.

Note: We have received reports of problems with this extension when the Tabs Studio plug-in is installed, as they both replace default behavior in the document tab well. Their latest version has been updated to work with the Pro Power Tools. As you might imagine, Tabs Studio will supercede almost all functionality of this extension.

However, if for some reason you cannot upgrade, you can still install the Pro Power Tools and disable this extension by running the following command (from a regular command prompt, or pressing Win+R):
reg add HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\10.0\DialogPage\Microsoft.DocWellBehavior.GeneralOptions /v Behavior /t REG_SZ /d Default

Radames Cruz Moreno – Software Developer, Visual Studio Platform Team
Biography: Radames arrived at Microsoft in 2008, just in time to help with development of Visual Studio 2010 since its early stages. He worked mainly helping develop the new WPF window docking system. Prior to that he worked in several interesting projects in Mexico using every technology and language imaginable, from C++ and Java to COBOL (shudder).

Walkthrough-- Publishing an Extensibility Web Control Project Template (Part 2 of 2)

Visual Studio Blog — Tue, 01 Jun 2010 18:32:00 GMT

Introduction

In Walkthrough-- Publishing a Custom Web Control (Part 1 of 2) you learned to create and publish a custom web control. You created the extensibility project manually, a procedure with many steps. Now that you have an extensibility project template, you can publish it to the Visual Studio gallery. Anyone who wants to create and publish a custom web control can download and install your template and create the project in one step.

In the second part of this walkthrough, you will learn to

Create a VSIX project template extension.
Publish the project template to the Visual Studio Gallery.
Install the project template from the Visual Studio Gallery.
Test the installed project template.
Remove the project template from the Visual Studio Gallery.
Add a debug action to the project template.

Prerequisites

To follow this walkthrough, you must have a working knowledge of web controls, creating new projects, setting project properties, and using the Visual Studio experimental instance. You must have both Visual Studio 2010 and the Visual Studio 2010 SDK installed on your computer. In addition, you must have completed the first part of this walkthrough.

Creating and Publishing an Extensibility Web Control Template

To create an extensibility web control project template, start with the custom web control project that you created in the first part of this walkthrough. Because this project includes the ColorTextControl web control, you can use this template to create custom web controls that render as colored text.

To publish a project template to the Visual Studio gallery, you must create the project template as a VSIX extension and provide it with an icon and a screenshot. The easiest way to do this is to use the Export Template as VSIX wizard.

1. Open the MyWebControls project in Visual Studio.

2. Use the Extension Manager to download the Export Template as VSIX wizard from the Visual Studio gallery. This adds the Export Template as VSIX … item to the File menu when a project is open.

3. Select the Export Template as VSIX menu item.

4. In the Choose Template Type page, make sure that Project Template is selected, and that the MyWebControls.csproj check box is checked. Click Next.

5. In the Select Template Options page, set the Template Name to Extensibility Color Text Web Toolbox Control and the Template Description to Color text web control project that produces a VSIX extension.

6. In the Icon Image text box, Browse to and select the Color.bmp file. You must set the file filter to All Files (*.*) to see this file.

7. In the Preview Image text box, Browse to and select the ScreenShot.bmp file. You must set the file filter to All Files (*.*) to see this file. Click Next.

8. In the Select VSIX Options page, change the Product Name to Extensibility Color Text Web Control Template.

9. Change the Company Name, and so forth, as desired.

10. Uncheck the Automatically import the template into Visual Studio check box, then click Finish.

In a moment, the Windows Explorer opens to display the Extensibility Color Text Web Control Template.vsix file in the <Users>\My Documents\Visual Studio 2010\My Exported Templates folder.

Publishing the web control project template VSIX file

You are now ready to publish your project template to the Visual Studio gallery.

1. Launch your web browser and navigate to http://visualstudiogallery.msdn.microsoft.com.

2. Click the sign in link in the upper right-hand corner.

3. Sign in with your Windows Live ID. If you don’t have one, you can create one here.

4. Click the Upload button in the upper right-hand corner.

5. In Step 1: Extension Type, select Project or Item Template, then click Next.

6. In Step 2: Upload, click the Browse button and select the Extensibility Color Text Web Control Template.vsix file located in the My Exported Templates folder. Click Next.

7. In Step 3: Basic Information, the information you entered into the Export Template as VSIX wizard appears.

8. Set the Category to ASP.NET and the Tags to toolbox, web control, templates.

9. Read and agree to the Contribution Agreement, then type the text image into the text box.

10. Click Create Contribution, then click Publish.

11. Search the Visual Studio Gallery for extensibility color text web control template. The new template listing appears.

Installing the web control project template

Now that your web control project template is published, install it in Visual Studio and test it there.

1. Return to Visual Studio.

2. From the Tools menu, select Extension Manager.

3. Click Online Gallery, then search for extensibility color text web control template. The Extensibility Color Text Web Control Template listing appears.

4. Click the Download button. After the extension downloads, click the Install button. Your project template is now installed in Visual Studio.

Testing the web control project template

You no longer have to create a custom web control the manual way, as you did in the first part of this walkthrough. Instead, you can use the Extensibility Color Text Web Control project template. In this section, you use the template to create a BlueColorTextControl web control.

1. Select the File/New Project menu item, then click the Online Templates tag in the left pane.

2. Select the ASP.NET node, then click Extensibility Color Text Web Control Template in the middle pane.

3. Set the Name to MoreWebControls, then click OK.

4. Rename the ColorTextControl.cs file to be BlueColorTextControl.cs.

5. Open the BlueColorTextControl.cs file.

6. In the ToolboxData attribute, replace both occurrences of ColorTextControl with BlueColorTextControl.

These values specify the opening and closing tags generated for the control when it is dragged from the Toolbox into a web page at design time. They must match the name of the control class, which is also the name of the control that appears in the toolbox.

The start of the control class source code now looks like this:

namespace MoreWebControls
{
    [DefaultProperty("Text")]
    [ToolboxData("<{0}:BlueColorTextControl runat=server></{0}:BlueColorTextControl>")]
    [ProvideToolboxControl("MoreWebControls", false)]
    public class BlueColorTextControl : WebControl
    {

7. In the get method, Change the color “green” to “blue”.

get
{
    String s = (String)ViewState["Text"];
    return "<span style='color:blue'>' + s + "</span>";
}

This surrounds the text with a span tag that colors it blue.

8. Build the MoreWebControls project.

Testing the new web control

Do not press F5 to launch an experimental instance of Visual Studio. Instead, launch it by following the steps below. You will learn more about adding a debug action to a project template in a later section.

1. Launch an experimental instance of Visual Studio explicitly by selecting the menu item Start/All Programs/Microsoft Visual Studio 2010 SDK/Tools/Start Experimental Instance of Microsoft Visual Studio 2010. For convenience, you can create a shortcut to this executable.

2. Create a new web application project.

3. Open default.aspx in Source mode.

4. Open the toolbox. You should see BlueColorTextControl in the category MoreWebControls.

5. Drag a BlueColorTextControl to the body of the web page.

6. Add a Text attribute with the value Think Blue! to the BlueColorTextControl tag. The resulting tag should look like this:

<cc1:BlueColorTextControl ID="BlueColorTextControl1" Text="Think Blue!" runat="server" />

7. Press F5 to launch the ASP.NET Development Server.

The BlueColorTextControl should render something like this:

8. Close the ASP.NET Development Server.

9. Close the experimental instance of Visual Studio.

Removing the project template

To add a debug action to your project template, you must delete the current template and recreate it. To delete the project template and the project it generated, follow these steps.

1. Return to your web browser.

2. Click the My Contributions link in the upper left-hand corner. The Extensibility Color Text Web Control Template listing appears.

3. Click Delete to permanently remove your project template from the Visual Studio Gallery.

4. Close the browser and return to Visual Studio.

5. From the Tools menu, select Extension Manager.

6. Select Extensibility Color Text Web Control Template, then click Uninstall.

7. Close the Extension Manager.

8. Close the MoreWebControls solution.

9. Close Visual Studio.

10. Delete the MoreWebControls project folder.

11. Start Visual Studio to complete the uninstall process.

Adding a debug action to the project template

If you press F5 while the MoreWebControls solution is open, you will see the error message “A project with an Output Type of Class Library cannot be started directly”. Your project template does not set a debug action because the location of the experimental instance of Visual Studio is unknown until the project template is installed on the target machine.

Microsoft extensibility project templates include an invisible wizard that runs during project template installation. This wizard determines the location of the experimental instance of Visual Studio and sets the debug action accordingly. You can create your own wizard to do the same. You only need to create this wizard once. You can use the same wizard with every extensibility project template you create.

The extensibility project template wizard must have a public implementation of Microsoft.VisualStudio.TemplateWizard.IWizard, and must be signed with a strong assembly name.

Creating the wizard

1. Create a new Visual C#/Windows/Class Library project named MyWizard.

2. Rename the file class1.cs to be MyWizard.cs.

3. Replace the MyWizard.cs file content with the following code.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.VisualStudio.TemplateWizard;
using System.Globalization;
using EnvDTE;

namespace MyWizard
{
    public class MyWizard : IWizard
    {
        public void BeforeOpeningFile(ProjectItem projectItem)
        {
        }
        public void ProjectFinishedGenerating(Project project)
        {
            foreach (Configuration config in project.ConfigurationManager)
            {
                //Set up the debug options to run "devenv /rootsuffix Exp";
                config.Properties.Item("StartAction").Value = 1;
                //Get the full path to devenv.exe through DTE.FullName
                config.Properties.Item("StartProgram").Value =
                    project.DTE.FullName;
                config.Properties.Item("StartArguments").Value =
                    "/rootsuffix Exp";
            }
        }
        public void ProjectItemFinishedGenerating(ProjectItem projectItem)
        {
        }
        public void RunFinished()
        {
        }
        public void RunStarted(object automationObject,
            Dictionary<string, string> replacementsDictionary,
            WizardRunKind runKind, object[] customParams)
        {
        }
        public bool ShouldAddProjectItem(string filePath)
        {
            return true;
        }
    }
}

4. Add the following references to the project. If there is more than one choice, choose the reference that has a path to Visual Studio 2010:

EnvDTE
Microsoft.VisualStudio.TemplateWizardInterface

5. In the Signing tab of the project properties dialog box, check the Sign the assembly check box.

6. In the Choose a strong name key file dropdown list, select <New…>. The Create Strong Name Key dialog box appears.

7. Set the Key file name to key.snk and uncheck the Protect my key file with a password check box.

8. Click OK. The key.snk file is added to the project.

9. Build the MyWizard project as a Release build. Your wizard is now ready to use.

10. Close the MyWizard solution.

Incorporating the wizard into the project template.

To incorporate the wizard into the project template VSIX extension, you must backtrack and set the path to your wizard in the Export Template as VSIX wizard Wizard text box.

Follow the steps beginning with the section Creating and Publishing an Extensibility Web Control Template, with these exceptions:

You do not have to download the Export Template as VSIX wizard again.
In the Wizard text box of the Select VSIX Options page of the Export Template as VSIX wizard, Browse to and select the bin/Release/MyWizard.dll file you created in the section above.

When asked to overwrite the existing VSIX extension output file, click Yes.

When you reach the section Testing the new web control, you can now launch the experimental instance of Visual Studio by pressing F5.

Summary

Congratulations! You have come full circle, from creating a web control project from scratch, to creating an extensibility web control project template.

Note that in this walkthrough, you use the Export Template as VSIX wizard to simplify the task of creating and publishing a project template. If you need more control of the project template, for example, to choose the icon that appears in the New Project dialog box, you must explicitly create the project template and wrap it in a VSIX extension. For more information, see Aaron Marten’s Creating and Sharing Project and Item Templates.

Short Bio: Martin Tracy is a senior programmer writer for the Visual Studio Project and Build team. As part of VS 2010, he has documented numerous features of the MSBuild system and Visual Studio platform. His long term focus is on developing infrastructure to build richly featured web applications. Martin has a long career in real-time software development, from artificial hearts and smart prosthetics to adaptive aeronautic controls. Martin holds a Masters degree in Dance Ethnology from the University of California, Los Angeles (UCLA), and a Bachelors degree in Asian Culture from Brown University, Rhode Island. He lives in Snohomish, WA with his extended family and loves to play accordion and watch anime in his spare time.

Walkthrough-- Publishing a Custom Web Control (Part 1 of 2)

Visual Studio Blog — Tue, 25 May 2010 21:12:00 GMT

The Visual Studio 2010 SDK adds several project templates to Visual Studio that let you create and share custom controls. These are called extensibility projects. In addition to compiling the control, the extensibility project prepares it for publication by incorporating it into a VSIX extension. A VSIX control extension can be shared by publishing it to the Visual Studio gallery, or by sending it directly to interested developers.

There is currently no extensibility web control project template in the Visual Studio SDK, but you can make your own by following the steps in this walkthrough. The walkthrough is divided into two parts:

Creating and publishing a custom web control the manual way.
Creating and publishing an extensibility web control project template.

On completion of the second part, you will have an extensibility project template that makes creating and publishing a web control a straightforward process.

In the first part of this walkthrough, you will learn to

Create a custom web control.
Test the web control in the Visual Studio experimental instance.
Prepare the web control for publication.
Publish the web control to the Visual Studio Gallery.
Install the web control from the Visual Studio Gallery.
Remove the web control from the Visual Studio Gallery.

Prerequisites

Creating and publishing your web control from scratch

To create and publish your custom web control when no project template is available, start with an existing extensibility control project and modify it to create an extensibility web control project.

1. Open Visual Studio and create a new Visual C#/Extensibility/Windows Forms Toolbox Control project named MyWebControls. Check Create directory for solution before clicking OK.

2. Add a new Visual C#/ASP.NET Server Control project named Temp to the solution.

Merging the project files.

1. Rename the file Temp/ServerControl1.cs to Temp/ColorTextControl.cs.

2. Delete the file MyWebControls/ToolboxControl.cs.

3. Copy the file Temp/ ColorTextControl.cs to the MyWebControls project.

4. Remove the Temp project from the solution.

Merging the project references

1. Add the following references to the project:

Microsoft.CSharp
System.Data.DataSetExtensions
System.Web
System.Xml.Linq

2. Remove the following references from the project:

System.Data
System.Windows.Forms
System.Xml

Creating the web control

1. Open the file ColorTextControl.cs in the code editor.

2. Change the namespace to MyWebControls.

3. In the ToolboxData attribute, replace both occurrences of ServerControl1 with ColorTextControl.

4. Add a ProvideToolBoxControl attribute to the control class.
The first argument to this attribute is the name of the assembly, which is the same as the namespace when the project is generated. The color text control will appear in a category in the toolbox with this name.

The start of the control class source code now looks like this:

namespace MyWebControls
{
    [DefaultProperty("Text")]
    [ToolboxData("<{0}:ColorTextControl runat=server></{0}:ColorTextControl>")]
    [ProvideToolboxControl("MyWebControls", false)]
    public class ColorTextControl : WebControl
    {

5. Replace the get method of the default Text property with this code:

get
{
    String s = (String)ViewState["Text"];
    return "<span style='color:green'>' + s + "</span>";
}

This surrounds the text with a span tag that colors it green.

6. Open the file Properties/AssemblyInfo.cs in the code editor.

7. Replace the AssemblyVersion Revision number with the “*” character.

[assembly: AssemblyVersion("1.0.0.*")]

Custom toolbox controls are cached and refreshed only when the assembly signature changes. By incrementing the assembly revision number with each build, the cache is always refreshed.

Testing your web control

Before publishing your web control, test it out in an experimental instance of Visual Studio.

1. Press F5 to launch an experimental instance of Visual Studio.

2. From the Tools menu, select the Extension Manager. The MyWebControls extension appears and is enabled.

3. Close the Extension Manager.

4. Create a new ASP.NET web application project.

5. Open default.aspx in Source mode.

6. Open the toolbox. You should see ColorTextControl in the category MyWebControls.

7. Drag a ColorTextControl to the body of the web page.

8. Add a Text attribute with the value Think Green! to the ColorTextControl tag. The resulting tag should look like this:

<cc1:ColorTextControl ID="ColorTextControl1" Text="Think Green!" runat="server" />

9. Press F5 to launch the ASP.NET Development Server.

The ColorTextControl should render something like this:

10. Close the ASP.NET Development Server.

11. Close the experimental instance of Visual Studio.

Preparing your web control for publication

Before you can publish your control to the Visual Studio Gallery, you need an icon and a screen shot. The icon you supply appears next to the extension in the Extension Manager.

1. If you have an icon image file, add it to your project as an existing item. Otherwise, add a new image file to your project and edit the image to represent the control. In this walkthrough, we use an icon called Color.bmp, which shows the Color letter “A” on a yellow field.

2. If you have a screenshot image file, add it to your project as an existing item. Otherwise, create a screenshot image file and add it to your project. In this walkthrough, we use a screen shot called ScreenShot.bmp, which shows the control as it appears in a web page.

3. Open the file source.extension.vsixmanifest for editing.

4. Change the Description to Color Text Web Control.

5. Set the Icon to Color.bmp and the Preview Image to ScreenShot.bmp.

6. Change the Author, Version, and so forth, as desired.

7. Save and close the manifest file, then rebuild the project as a Release build. Publishing your web control

Publishing your web control

You are now ready to publish your web control to the Visual Studio gallery.

1. Launch your web browser and navigate to http://visualstudiogallery.msdn.microsoft.com.

2. Click the sign in link in the upper right-hand corner.

3. Sign in with your Windows Live ID. If you don’t have one, you can create one here.

4. Click the Upload button in the upper right-hand corner.

5. In Step 1: Extension Type, select Control, then click Next.

6. In Step 2: Upload, select I would like to upload my control. The Select your control text box appears.

7. Click the Browse button and select the MyWebControls.vsix file located in the project bin/Release folder. Click Next.

8. In Step 3: Basic Information, you see the information you entered into the manifest editor. The description you entered appears in the Summary field.

9. Set the Category to ASP.NET and the Tags to toolbox, web control. You can enter a more detailed description at this time.

10. Read and agree to the Contribution Agreement, then type the text image into the text box.

11. Click Create Contribution. A warning appears that This page has not yet been published.

12. Click Publish.

13. Search the Visual Studio Gallery for MyWebControls. The MyWebControls extension listing appears.

Installing your web control

Now that your web control is published, install it in Visual Studio and test it there.

1. Return to Visual Studio.

2. From the Tools menu, select Extension Manager.

3. Click Online Gallery, then search for MyWebControls. The MyWebControls extension listing appears.

4. Click the Download button. After the extension downloads, click the Install button. Your web control is now installed in Visual Studio.

6. Create a new ASP.NET web application project.

7. Open default.aspx in Source mode.

8. Open the toolbox. You should see ColorTextControl in the category MyWebControls.

Removing your control from the Visual Studio Gallery

In the next part of this walkthrough, you will create your web control from a project template. In preparation, delete your web control.

1. Return to your web browser.

2. Click the My Contributions link in the upper left-hand corner. The MyWebControls listing appears.

3. Click Delete to remove your web control until you upload it again.

4. Return to Visual Studio.

5. From the Tools menu, select Extension Manager.

6. Select MyWebControls, then click Uninstall.

7. Restart Visual Studio to complete the uninstall process.

This is the end of part one of this walkthrough. Part two shows you how to create and publish an extensibility web control project template based on the web control project you created above. To continue, please see Walkthrough-- Publishing an Extensibility Web Control Project Template (Part 2 of 2).

Short Bio: Martin Tracy is a senior programmer writer for the Visual Studio Project and Build team. As part of VS 2010, he has documented numerous features of the MSBuild system and Visual Studio platform. His long term focus is on developing infrastructure to support richly featured web applications. Martin has a long career in real-time software development, from artificial hearts and smart prosthetics to adaptive aeronautic controls. Martin holds a Masters degree in Dance Ethnology from the University of California, Los Angeles (UCLA), and a Bachelors degree in Asian Culture from Brown University, Rhode Island. He lives in Snohomish, WA with his extended family and loves to play accordion and watch anime in his spare time.

Three New Managed Package Framework features for Visual Studio 2010

Visual Studio Blog — Sun, 16 May 2010 23:00:00 GMT

This post describes three new features that have been added to the Managed Package Framework (MPF) version 10.0 in Visual Studio 2010. These features are available to anyone developing extensions in managed code for Visual Studio 2010. To get started building extensions for Visual Studio, start by visiting the Visual Studio Extensibility Developer Center on MSDN and then go and download the Visual Studio 2010 SDK.

To use these features, your extension must reference the assembly Microsoft.VisualStudio.Shell.10.0.

1. ServiceProvider.GlobalProvider

This new static property on the ServiceProvider class allows access to the global service provider from any code, as long as it is called from the main UI thread. This property is closely related to the Package.GetGlobalService static method which was available in previous versions of the MPF. The problem with Package.GetGlobalService was that it would fail if a package had not yet been initialized. This led to subtle ordering bugs in code that used the MPF libraries without initializing a package of their own. Sometimes they would work only because another package had already initialized the global ServiceProvider on their behalf. If that other package was uninstalled, or perhaps moved to a different version of the MPF, that static would no longer be initialized causing Package.GetGlobalService to fail.

Now, in MPF 10, you can call ServiceProvider.GlobalProvider at any time as long as you are calling from the UI thread. For compatibility, this mechanism will still use the ServiceProvider created by the first Package to be sited but, in the case where no Package has yet been initialized, MPF 10.0 now has the ability to obtain the global provider from the registered COM message filter. Package.GetGlobalService() is also hooked up to this new mechanism.

2. ActivityLog

The activity log is a feature first introduced in Visual Studio 2005 for diagnosing package load failures. In Visual Studio 2010, we started to log a few more things to the activity log and would like to promote it as the service for all extensions to use for low-frequency diagnostics. To that end, we created a very simple-to-use ActivityLog class. It’s small enough to post the public interface here.

/// <summary>
/// Class which provides convenient managed methods for logging messages to the IVsActivityLog.
/// </summary>
public static class ActivityLog
{
    /// <summary>
    /// Gets the path to the activity log for the current application.
    /// </summary>
    public static string LogFilePath { get; }

    /// <summary>
    /// Logs an error message in the activity log with the given source.
    /// </summary>
    /// <param name="source">A name associated with the source contributing the message.</param>
    /// <param name="message">The message to be written to the activity log.</param>
    public static void LogError(string source, string message);

    /// <summary>
    /// Logs a warning message in the activity log with the given source.
    /// </summary>
    /// <param name="source">A name associated with the source contributing the message.</param>
    /// <param name="message">The message to be written to the activity log.</param>
    public static void LogWarning(string source, string message);

    /// <summary>
    /// Logs an information message in the activity log with the given source.
    /// </summary>
    /// <param name="source">A name associated with the source contributing the message.</param>
    /// <param name="message">The message to be written to the activity log.</param>
    public static void LogInformation(string source, string message);
}

All public methods and properties on the class are static which makes it incredibly easy to use from your own code. e.g.:

ActivityLog.LogInformation("ACME Widget Package", "The widget is disconnected");

Internally, of course, ActivityLog uses ServiceProvider.GlobalProvider to locate the global service provider.

I have to give credit and thanks for this idea to István Novák, one of our MVPs, who regularly visits us in Redmond to attend and also present at our Visual Studio developer clinics. István has developed a set of managed classes called “VSXtra” for easing the development of managed packages by providing a useful set of helper classes. This new class was inspired by a discussion I had with him at the Developer Tools Summit last October and was incorporated into MPF 10.0 with his permission.

3. ThreadHelper

The ThreadHelper class allows managed code running on any thread to run operations on the UI thread. This may be necessary if you are calling into a component that is not thread-safe and must be called on the UI thread. This mechanism is preferred over other existing techniques like Dispatcher.Invoke from WPF or Control.Invoke from Windows Forms because neither of these is “RPC aware” and using them may result in deadlocks in some scenarios. As you may know, Visual Studio is heavily rooted in COM and RPC is the primary mechanism used by components to communicate across threads or processes.

Under the covers, ThreadHelper makes a private cross-apartment COM call to the UI thread where the ‘invokable’ operation completes. By using a genuine COM call, we maintain what’s known as “logical thread identity” throughout the call. If the call to the UI thread is itself part of a cross-thread COM call, then it will be recognized as part of the same call (CALLTYPE_NESTED) and not a new top-level call. Both WPF’s and Windows Forms’ invoke operations post private messages to the UI thread and this breaks the chain of logical thread identity.

ThreadHelper really has only one interesting method, Invoke, although it takes two forms:

public void Invoke(Action action);
public TResult Invoke<TResult>(Func<TResult> method);

The argument passed to Invoke is a delegate for the operation you want to perform on the UI thread. If the caller is already on the UI thread, then the delegate is invoked directly. If the operation throws an exception, then the exception is re-raised on the calling thread.

Using ThreadHelper in your own code is straightforward, but note that ThreadHelper itself is abstract to allow for advanced extensibility. Most of the time, you’ll use the general purpose implementation accessed through the static property ThreadHelper.Generic. Here’s an example:

public class MyComponent
{
    public string Name 
    {
        get
        {
            // The Name property may be accessed from any thread, but the
            // implementation requires that the call comes in on the UI thread.
            return ThreadHelper.Generic.Invoke(() => GetName());
        }
    }

    // Must be called on the UI thread
    private string GetName()
    {
        // ...
    }

    // ...
}

Conclusion

I hope you’ll find these three new features useful when developing your own managed extensions to Visual Studio 2010. As always, please feel free to use the comment stream to ask questions.

Paul Harrington – Principal Developer, Visual Studio Platform Team.
Biography: Paul has worked on every version of Visual Studio .Net to date. Prior to joining the Visual Studio team in 2000, Paul spent six years working on mapping and trip planning software for what is today known as Bing Maps. For Visual Studio 2010, Paul designed and helped write the code that enabled the Visual Studio Shell team to move from a native, Windows 32-based implementation to a modern, fully managed presentation layer based on the Windows Presentation Foundation (WPF). Paul holds a master’s degree from the University of Cambridge, England and lives with his wife and two cats in Seattle, Washington.

Announcing: Collapse Selection in Solution Explorer extension

Visual Studio Blog — Thu, 13 May 2010 21:15:00 GMT

We have received much feedback asking for a feature that would recursively collapse nodes in the solution explorer. We are happy to announce the Collapse Selection in Solution Explorer extension!

What is the Collapse Selection in Solution Explorer extension?

Many Visual Studio users have a solution tree structure with multiple projects and solution folders that are organized as a deep hierarchy. To avoid visual pollution, users want only those projects expanded that are being actively developed (often with many of the project’s child nodes recursively collapsed). To accomplish this task, they have to manually collapse each node recursively – an onerous chore if one has a deeply nested solution tree. The Collapse Selection in Solution Explorer extension addresses this particular issue by enabling the user to recursively collapse multiple nodes with a single click.

How do I install the extension?

1. You can download the extension from the VS Gallery. Double-click the downloaded VSIX file and the extension will be installed.

2. You can navigate to Tools –> Extension Manager, and search for “Collapse Selection in Solution Explorer” in the Online Gallery. Simply download and click Install.

How does the extension work?

Once the extension is installed, you will see a button appear in the Solution Explorer bar. Choose any collapsible node (any node with children nodes; i.e. parent node) in the Solution Explorer and click the Collapse Selection button. All the children nodes will be recursively collapsed to show only the parent node. When you click the expand/collapse icon next to the just collapsed parent node, the parent node will expand to list all the children nodes which will appear collapsed if they have their own children nodes (see figure below). You can select the solution node and click the Collapse Selection button to recursively collapse all nodes in the solution tree. You can also select multiple collapsible nodes and click the Collapse Selection button to recursively collapse each of them.

I prefer using my keyboard. Is it possible to use this extension through keyboard shortcuts?

Definitely. Ensure that the focus is on the Solution Explorer and press Alt + Num(-) to collapse selected nodes. You can also use the Command Window by entering the following command: View.CollapseSelectionInSolutionExplorer.

Is this extension limited to certain project types?

No. This extension should work with all project types.

How can I provide feedback?

We love feedback!

1. Comment on this blog post.

2. Log onto Connect and file a bug.

Richa Prasad – Program Manager, Visual Studio Project Team

Short Bio: I am a PM on the Visual Studio Project System team. I work on many Project features such as conversion, solution load, references, project properties and others. Prior to joining Microsoft, I was a graduate student at University of Washington.

Open thread: Extensibility is the future?

Visual Studio Blog — Thu, 06 May 2010 19:15:00 GMT

With the release of Visual Studio 2010 came a major improvement to the overall extensibility story of Visual Studio; the new editor. With the new editor VS was introduced to a Managed Extensibility Framework (MEF) based API that opened up possibilities you could barely dream of in previous versions of VS. Inside of the editor you’re able to do nearly anything, from adding visualizations to using multiple fonts in the same file. For us, the extensibility we present with the editor is an important step forward, especially when you consider what people in the industry are starting to say about the future of software. As such, I want to ask you, our users/followers/critics, is extensibility the future? What do you think of the steps we’ve taken with the new MEF extensibility in the editor? How do you feel about the VSIX format? And lastly, where do you think we should go?

(Open threads are designed to be a discussion seeded by some little blurb, so comment away!)

Cheers,
Chris Granger

Custom Build Steps, Tools, and Events

Andrew L Arnott — Mon, 26 Apr 2010 18:51:22 GMT

The VC++ build system is of course MSBuild based in VS 2010. This automatically gives you a great deal more flexibility to customize your build than you had with .vcproj project files in prior releases. We went out of our way to ensure that the .targets files that drive the build of a .vcxproj file in VS 2010 leverage as much MSBuild flexibility as possible.

Some build extensions are very simple: just execute a hard-coded command at a given place and time during the build. Others are more complex: any time you see a *.crt file run a custom tool on it, setting parameters based on properties on that item, etc. We wanted to keep the simple scenarios simple, and save the complexity that comes with flexibility for only those scenarios that needed it. This post will discuss a couple of the simple build extension options you have, and how they’ve changed since VS 2008.

In VS 2008, Visual C++ had a couple of the simple scenarios called Custom Build Step and Custom Build Tool. Actually these ideas ran together in not so obvious ways in 2008 which made them a bit confusing despite their intention to support the simple scenarios. So let’s just look at what they are in VS 2010.

Foreword about build extensions

First some overall truths about these build extensions:

For each of these build extensions, the command line that is executed is stored in the MSBuild project file as item [definition] metadata, which means you can use any existing project property you want in assembling the command line.
The command gets emitted into a batch file and executed, so your command line is processed as one command per line, allowing multiple commands to be executed.
Any command works, even “echo”, since the command is actually passed to cmd.exe for processing.
The command executes synchronously, so the rest of the project’s build is held up while your command is executing.
If the command you execute returns a failing error code, the entire build fails.
The command runs with the VC environment variables and path set (unless you go out of your way to schedule the command to run before the SetEnv target).
There is a :VCEnd label emitted at the end of the generated command file, which can be used to skip the rest of your commands with “goto VCEnd”
You can see the output of the executed command in the Visual Studio Output window under normal verbosity, and can see the actual command itself with verbosity set to detailed.

Custom Build Step

Custom Build Steps are the quick (but not dirty) way to get an arbitrary command executed at a specific point during the build. The Custom Build Step is a project level build step (meaning it runs only once during a project build rather than once per file).

The way the Execute After and Execute Before properties work may not be totally obvious. It hooks into MSBuild’s new “before and after” targets feature, which allows an MSBuild target to declare any arbitrary target included in the project (or its imports) that this target should run before or after. Important ramifications of this include:

The custom build step only runs when one of the targets you select are run as a normal part of the build. So if you select “Execute After: CLCompile”, and the CLCompile target doesn’t run because the target’s Condition evaluates to false then will your custom build step won’t run either. Note that if CLCompile’s Condition evaluates to true, but is skipped anyway because MSBuild deems the target is up to date already, its before and after targets execute anyway.
You can list multiple targets as a semi-colon delimited list.
The custom build step runs only once during the build, at the first qualifying opportunity – not before and after every target you listed. So if you say “Execute Before: CLCompile” and “Execute After: Build”, then during the build, whichever of those happens first will determine when your custom build step runs, and the second qualifying point in the build (if there is one) will not execute the custom build step a second time.

When your Custom Build Step runs (or doesn’t!)

Custom Build Steps are included as part of the intelligence that drives incremental build using the “Additional Dependencies” and “Outputs” properties. If a file in your “Additional Dependencies” property is touched, then your Custom Build Step will be considered out of date and will build with your next build (as long as the .targets it runs before/after are also run).

The Outputs property is a semicolon-delimited list of files, and must list whatever files are generated as part of the execution of your custom build step. If you leave your Outputs property empty, your Custom Build Step will never execute, since MSBuild will determine that no outputs are out of date. If your step doesn’t generate files but you still want it to execute with every build, making up a fake filename will do the trick, since that file will never exist and MSBuild will always determine that the custom build step is out of date. However, before you do this, consider Build Events (below).

Custom Build Tool

Custom Build Tools allow you to execute a custom command line for an individual source file as part of the build. Custom Build Tool is a file level build extension, and without a source item being marked CustomBuild, this tool won’t do anything. You can right-click a CustomBuild project item in Solution Explorer and click Compile to invoke your custom build tool.

Any source item (read: file in your project) can have a custom command line executed during the build by setting its Item Type property in the property pages for that item to “Custom Build Tool” (or CustomBuild in the project file directly). If using the UI, be sure to click Apply to see the Custom Build Tool property page appear.

In the Custom Build Tool property page, you may notice it looks very similar to the Custom Build Step property page. This is more by coincidence than design. But there is a legacy-compatibility link between Custom Build Step and Custom Build Tool in VS2010: custom build tools always run at the time the custom build step would run; except when it doesn’t. When no value is specified for Execute Before and Execute After for the Custom Build Step, the before and after targets for custom build step and custom build tool vary (go figure) in order to maintain compatibility with VS 2008. In all other ways these two build extensions are totally unrelated.

Custom Build Tool is targeted at the exceptional source item case (you have just one source item that needs this kind of command executed on it) rather than a group of files. If you’re trying to set up a command that runs on all .customextension files, you should consider using a Custom Build Rule (now called Build Customization) rather than a Custom Build Tool, as that is exactly what custom build rules are for.

If Custom Build Tool is file-level, why do you see Custom Build Tool in your project level property pages? Because just like any other tool (i.e. CL or Link), you can set project-level defaults for its properties. But these properties have no impact on the project itself… only on project source items that are of the CustomBuild type.

Build Events

Nothing much changed here since VS2008. These three events (Pre-build, Pre-link, and Post-build) fire during the course of a normal build and allow you to execute arbitrary project-level commands.

Start Extending Visual Studio 2010!

Visual Studio Blog — Wed, 21 Apr 2010 16:05:00 GMT

Visual Studio not only boasts a wide variety of tools to improve developer productivity, but it is also extremely extensible so that it can be tailored and customized to serve specifically your needs. In fact, one of the key benefits of Visual Studio 2010 is its improved extensibility story. With an easier deployment experience, more extensive yet simpler extensibility API, and ability to create advanced visuals directly on the Editor’s surface, you can extend Visual Studio more easily and quickly than ever before!

We have many great resources to help you get started with writing Visual Studio extensions:

Visual Studio 2010 SDK (explore at MSDN) includes project templates to help you create tool windows, menu commands, isolated shell projects, and editor extensions. The SDK also includes build tasks to help you build and debug extensions.
Visualization and Modeling SDK (explore at MSDN) provides tools and templates for building Visual Studio Domain Specific Language designers for Visual Studio 2010 and extending UML and Layer designers. By using this SDK, you can build your own graphical or form-based designers for Visual Studio 2010 and extend existing tools.
Visual Studio Developer Center is the nexus for any Visual Studio related information. It links to downloads, explains how to write and publish your own extensions, hosts forums to discuss best practices and development issues, points to documentation on any and all Visual Studio features, and surfaces many other useful sources of information.
Visual Studio Extensibility Code Gallery presents many Visual Studio 2010 code samples that illustrate how to write extensions. Examples include writing your own debug engine, language service, or custom source control, among many other Debugger, Editor, Shell, Project, and MSBuild samples.

We hope these resources will be of great help to you. As always, we are happy to hear your feedback. Please comment on this blog post to do so.

Richa Prasad – Program Manager, Visual Studio Project Team

Custom Extension Types with VSIX

Aaron Marten — Fri, 16 Apr 2010 21:23:00 GMT

DISCLAIMER: While the following technique is supported in Visual Studio 2010, the interfaces and methods exposed by Microsoft.VisualStudio.ExtensionManager.dll are likely to change in future Visual Studio releases. If you create an extension that relies on Microsoft.VisualStudio.ExtensionManager.dll, there is no guarantee that your extension binary will work on future Visual Studio releases without code changes.

If you’ve used the VSIX Manifest editor when creating an extension for Visual Studio 2010, you may have noticed the various options when you add content to the VSIX container. Clicking the “Add Content” button will bring up a dialog that allows you to select a content type.

Most of the choices are well-known types that Visual Studio already knows how to consume:

Project/Item Template: A collection of VSTemplate zip files from which a user can create projects and project items.
Template Wizard: An assembly (distributed with one or more VSTemplates) that contains a template wizard extension to show UI or perform custom logic at template instantiation time.
VS Package: A PkgDef file containing configuration information for a VSPackage.
MEF Component: An assembly to be queried and consumed by the VS MEF Host for extending the core text editor and other MEF-based subsystems in the IDE.
Toolbox Control: An assembly containing one or more controls to publish on the Toolbox for use in the various UI designers in Visual Studio.

You may be wondering what the “Custom Extension Type” entry (highlighted above) is and why you would want to use it.

Let’s say you want to ship an extension to Visual Studio that is itself extensible. If the extensibility points you are exposing involve managed code, a MEF-based solution would be a reasonable option to consider. However, imagine that what you consume from your extenders is more like data or content rather than code. [For a real world example, consider the built-in Project/Item Template extension content types.] In this case, having these extension authors create an assembly (and having Visual Studio load and manage it at runtime) simply to provide data or content is too heavyweight.

This is where the content with a Custom Extension Type comes in handy. “OK”, you may be thinking. “But why couldn’t I just have end-users put these content files into a certain directory on the local machine where my extension would find them?” You certainly could. However, the advantage of using VSIX content with a Custom Extension Type is that the content can be managed by the end-user via the Extension Manager. Installing and removing the content is exactly the same user experience as for any other extension.

Walkthrough: Consuming Custom Extension Content

Let’s create an extension to demonstrate consuming custom content distributed in a VSIX. In this walkthrough, we’ll create a tool window called Image Browser that queries the Extension Manager for content of type WalkthroughImage. Then, we’ll create another extension that provides the content that our tool window will consume. (You must have the Visual Studio 2010 SDK installed to complete the walkthrough.)

Open the New Project dialog to create a new Visual Studio Package from the Extensibility category under Visual C# called “ImageBrowser”.
In the Visual Studio Package Wizard, select the “Tool Window” option on Page 3.
Rename “My Tool Window” to “Image Browser” on Page 5.
After completing the wizard, replace the content inside the <Grid> element in MyControl.xaml with the following:
```
<ScrollViewer>
  <WrapPanel Name="wrapPanel1" />
</ScrollViewer>
```
Add a reference to Microsoft.VisualStudio.ExtensionManager.dll (located in <VSInstallDirectory>\Common7\IDE\PrivateAssemblies)

In MyControl.xaml.cs, add the following method:

internal void AddImageFromPath(string path)
{
    const int ImageWidth = 250;
    BitmapImage bitmapImage = new BitmapImage();
    bitmapImage.BeginInit(); 
    bitmapImage.UriSource = new Uri(path); 
    bitmapImage.DecodePixelWidth = ImageWidth; 
    bitmapImage.EndInit(); 
    this.wrapPanel1.Children.Add(new Image() 
    { 
        Source = bitmapImage, MaxWidth = ImageWidth 
    });
}

Close MyControl.xaml.cs
Open MyToolWindow.cs and add the following using statement:
```
using Microsoft.VisualStudio.ExtensionManager;
```

Add the following code at the end of the MyToolWindow constructor:

//Query the Extension Manager for content of type "WalkthroughImage" const string WalkthroughImageContentType = "WalkthroughImage"; 
IVsExtensionManager extensionManager = ServiceProvider.GlobalProvider.GetService(typeof(SVsExtensionManager)) as IVsExtensionManager;
if (extensionManager != null)
{
    foreach (string image in extensionManager.GetEnabledExtensionContentLocations(WalkthroughImageContentType)) 
    { 
        ((MyControl)base.Content).AddImageFromPath(image); 
    }
}

Press F5 to debug the extension in the Experimental instance. You can show the tool window you just created from Views –> Other Windows –> Image Browser, but there won’t be any images in the tool window just yet.
Close the Experimental instance and return to your previous VS instance.

Walkthrough: Creating an Extension with Custom Content

Now let’s create another extension that will provide content to our tool window we just created. We’ll create a VSIX containing the sample images included in Windows 7 so that they display in our Image Browser tool window.

In the Solution you created in the previous walkthrough, add a New Project to the solution.
In the New Project dialog, select the “VSIX Project” template from under Visual C# –> Extensibility or Visual Basic –> Extensibility. (There won’t be any code to compile, so the language choice here doesn’t matter.)
Name the project SampleImagePack and Click OK.
In the VSIX Manifest Designer after the project is created, click the “Add Content” button.
Choose “Custom Extension Type” for the content type.
In the Type field, enter “WalkthroughImage”. (without the quotes)
For the source, choose the File radio button and navigate to the Sample Pictures in Windows. (They are located in the Public Pictures folder.)
Select one of the images in the folder.
Click OK in the Add Content dialog.
Repeat steps 4-9 for each image you wish to add.
Press F5 to debug both the Image Browser tool window extension and the SampleImagePack extension in the Experimental instance.
Show the image browser tool window from View –> Other Windows –> Image Browser and notice that the images added to the SampleImagePack are now displayed in the ImageBrowser control.
(optional) You can repeat the steps above to create multiple image pack VSIX’s which will be merged together in the Image Browser tool window.

When you bring up the tool window, you should see something like this:

We’re looking forward to seeing how you use this functionality for your own extensions! As always, please let us know what you think.

Aaron Marten - Developer, Visual Studio Platform

Short Bio: Aaron has been on the Visual Studio team for over 6 years with a focus on extensibility. For Visual Studio 2010, Aaron worked on the Extension Manager and the Visual Studio SDK. In addition to contributing to the Visual Studio blog, he also writes about extending the IDE on his own blog at http://blogs.msdn.com/aaronmar.

Troubleshooting pkgdef Files

Visual Studio Blog — Mon, 22 Mar 2010 13:35:00 GMT

For those using the Visual Studio 2010 SDK to create extensions for Visual Studio, you should find the creation and use of .pkgdef files to be mostly automatic (see What's a PkgDef and Why?). However, like anything involving computers and software, there are occasions that require manual intervention because they aren’t covered by the automatic settings or things can go wrong. This article illustrates some possible issues with .pkgdef files and provides techniques for discovering what’s wrong and correcting them.

Please note that these techniques apply not only to the Visual Studio 2010 IDE, but also to applications built using the Visual Studio 2010 Shell (Isolated) (or Integrated). All of the examples assume the case of VS 2010 running on 32-bit Windows 7. For other cases, substitute the appropriate file locations and names and registry root key.

What Could Go Wrong?

First of all, how do you know if something goes wrong? A problem with a .pkgdef file usually manifests itself in one of two ways:

All or part of a Visual Studio extension, such as a VS Package, simply fails to load or an error message is displayed about needing to reinstall Visual Studio.
Your Visual Studio extension tries to retrieve a registry value it expected to be included in the install and does not find it. The result can be anything from using an appropriate default to displaying a message about an exception.

Either of these symptoms can be caused by one or more of the issues listed below. The list is by no means intended to be exhaustive.

Issue: Per-user Extension Is Not Enabled

Pkgdef files that are installed as part of a user extension deployed using the new VSIX format are copied to a sub-folder of %LocalAppData%\Microsoft\VisualStudio\10.0\Extensions. The pkgdef loader does not automatically search for pkgdef files here. Rather, it loads pkgdef files for user extensions that have been enabled, which the Extension Manager and the stand-alone VSIX installer both do automatically. If you choose to unpack a VSIX file yourself, or otherwise do a manual xcopy-style deployment, it’s easy to forget the step that enables the extension. This is easily fixed.

Remedy: Use the Extension Manager to enable per-user extensions

It’s entirely possible that if you manually deployed the contents of a VSIX file, you simply need to enable it in the Extension Manager dialog and restart Visual Studio before the pkgdef loader will pick it up.

Remedy: Enable per-user extensions when running as administrator

On a related note, there is an option to disable loading of all per-user extensions when running ‘as administrator’ (elevated), regardless of being enabled or not. This is controlled under Tools-Options-Extension Manager as Load per user extensions when running as administrator. Make sure this checkbox is checked (when appropriate).

Issue: pkgdef File Is Not Found

For all other extensions (those that are not per user), the pkgdef loader searches the locations listed in the PkgDefSearchPath of the master pkgdef file. The value of PkgDefSearchPath has three elements:

$RootFolder$\Common7\IDE\Extensions
$RootFolder$\Common7\IDE\CommonExtensions
$RootFolder$\Common7\IDE\devenv.admin.pkgdef

$RootFolder$ is the location where Visual Studio is installed (C:\Program Files\Microsoft Visual Studio 10.0). The first two search elements are folders, which are recursively scanned looking for pkgdef files. The third element is a specific pkgdef file (which does not typically exist, but is kept in the list as a placeholder for system administrators).

An easy mistake to make is to drop a pkgdef file into either $RootFolder$ or $RootFolder$\Common7\IDE or some other sub-folder and expect the pkgdef loader to just find it. However, these locations are not in the search path.

Remedy: Use /log to discover which pkgdef files are loaded

You can find out exactly which pkgdef files the loader is finding, using the /log command line option for Visual Studio. Among the items the pkgdef loader logs are the full expanded value for the PkgDefSearchPath, a list of all of the pkgdef files found on the search path, and a list of the pkgdef files found for enabled extensions.

Trick
Since the pkgdef loader will not rebuild the cache if it does not think it is out of date, there is a bit of a trick to using /log to debug pkgdef load issues when you are not sure which files it is finding (and thus which ones to touch). Use Notepad to create a file called “log.pkgdef” that contains a single comment line (“// comment”) and copy it to C:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE\Extensions. This ensures that the pkgdef loader has a new file to process. If you need to run /log more than once with this file in place, be sure that it gets saved with a new timestamp before each run.

Run: devenv.exe /log

When Visual Studio is finished loading (status bar reads “Ready”), File - Exit, start Windows Explorer, browse to C:\Users\User\AppData\Roaming\Microsoft\VisualStudio\10.0, and open the file ActivityLog.xml. It should open in Internet Explorer using the associated XSL to format it in an table.

Near the top of the file, Visual Studio will list the PkgDefSearchPath:

This is followed by the number of files found and then the list of those files, for example:

Armed with the knowledge of which folders are being scanned and which pkgdef files were discovered, you should now be able to make sure your pkgdef file is deployed to an appropriate location.

Remedy: Install System-wide extensions under the PkgDefSearchPath

Any extension that is not installed per-user should be installed in a sub-folder of $RootFolder$\Common7\IDE\Extensions or $RootFolder$\Common7\IDE\CommonExtensions.

Issue: Invalid Syntax

This issue is most likely to crop up if you run into a situation where you must create or edit a pkgdef file manually. Like any language, it’s easy to forget a closing quote or insert an extra one.

The syntax of a pkgdef file is actually quite simple. Each line can be one of:

comment – starts with a semi-colon (‘;’') or double-slash (‘//’)
registry key – starts with a square bracket (‘[‘) and ends with a square bracket (‘]’) that defines a section of values
registry value – starts with a name in double quotes or the at sign (‘@’ not in quotes) for a ‘default’ value of a key, followed by an equals sign, and then a string or numeric value

Common syntax mistakes include:

Not enclosing a registry value name in double quotes:
incorrect: name=”value”
correct: “name”=”value”
Enclosing the symbol for the default value of a registry key in double quotes:
incorrect: “@”=”value”
correct: @=”value”
Omitting an opening or closing double quote for a name or string value
Adding comments at the end of a line defining a key or value. Comments must be on their own line.

The pkgdef loader is not very tolerant of syntax errors and will simply refuse to load a pkgdef file that contains even a single error, rather than risk corruption of the pkgdef cache. When it does reject a pkgdef, this information is written to the activity log.

Remedy: Use /log to discover pkgdef file syntax errors

Use /log to generate ActivityLog.xml. Any syntax errors will be highlighted in red, along with a warning showing the name of the offending file (which is not loaded).

In this example, the value of “foo” is missing the closing quote expected for strings and the value of bar is given as word, rather than dword or qword. The name for “bax” is not put in quotes. Once you edit the file to make these corrections (and save it and deploy it to the correct location), the pkgdef loader will see that the file has been updated and rebuild the cache automatically (you do not have to force this rebuild by deleting the registry value from the cache again).

Remedy: Use the PkgDef Editor extension for Visual Studio

Another way to find and fix syntax errors is to download and install the new editor extension we’ve created to give syntax coloring and error output for pkgdef files. It can be found in the Visual Studio gallery, either through the Extension Manager or directly in the gallery. Just search for “pkgdef” under the Tools category and download the PkgDef Editor extension.

In this example, the same errors as above are flagged, along with the pop-up message describing the problem with the value of “foo”.

Issue: Unrecognized Substitution String

pkgdef files are made portable by tokenizing system-specific and user-specific information. These are known as substitution strings. Examples are $RootKey$, which defines the root of the Visual Studio configuration registry, the starting point for all key values, and $PackageFolder$, which is the full path in the file system to the location from where the current pkgdef file is being loaded.

Substitution strings are case-sensitive and must be enclosed between two dollar-signs (‘$’). Common mistakes related to tokens are:

Omitting the closing dollar-sign" on a substitution string name:
incorrect: [$RootKey\subkey]
correct: [$RootKey$\subkey]
Using incorrect case or spelling:
incorrect: “pathtomyfile”=”$packagefolder$\myfile.dll” or “$pkgfolder$\myfile.dll”
correct: “pathtomyfile”=”$PackageFolder$\myfile.dll”

When the pkgdef loader cannot recognize a substitution string, it simply does nothing and uses it ‘as is’. When this happens in a registry key or value name, it means the key or value will not be put in the correct location or get the correct name.

Remedy: Search the registry

This can be very difficult to debug, except by knowing what to look for. When this happens for a string value, it is a little easier to detect, simply by looking in the registry using regedit.exe:

In this example, the value for “bax” was specified with “$PkgFolder$”, rather than “$PackageFolder$”.

Remedy: Use PkgDef Language Integration for Visual Studio

As seen above, the PkgDef Editor extension can make it much easier to see problems with pkgdef files. In particular, it knows the valid tokens for string substitution and can flag the ones it does not recognized:

In this example, all of the string substitution tokens (anything starting and ending with the dollar-sign) are highlighted (in blue) and the unrecognized tokens are flagged as errors. One string contains a value that was intended to be a string substitution, but is missing the closing dollar-sign, so it is not highlighted. Also in this example, it is easy to see that $RegRoot$ is not a recognized string substitution, but using regedit it was simply missing-in-action.

Issue: Invalid Registry Key

The pkgdef loader will not write to arbitrary registry locations. It only writes registry entries within the configuration hive of Visual Studio (or an Visual Studio Shell (Isolated) application). This rule is easily followed by starting all key/section names with $RootKey$.

Remedy: Use /log to discover invalid registry keys

The pkgdef loader will log attempts to write to locations outside of the application’s configuration hive:

In this example, using the file from the previous example, $RegRoot$ was not recognized as a substitution string, so it did not get replaced with the appropriate root key for the application. And the result is not a valid location for a registry key for the application.

Issue: Registry Value Collisions

Sometimes the same registry value is being set by more than one pkgdef file. In other cases, a registry value is being set, but it’s not clear which pkgdef file is doing it. You can either scan all of the pkgdef files and discover where the value is being set. Or use /log again.

Remedy: Use /log to discover which pkgdef(s) set a value

To discover all pkgdef files that are setting a value, use a simple trick: explicitly set that same value by temporarily changing the master pkgdef (C:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE\devenv.pkgdef) to explicitly set the value before all of the other pkgdef files are processed. This will require Administrator rights to edit the file, but is otherwise straightforward. Make a backup copy of devenv.pkgdef, then bring it up in an editor. Below the [$Initialization$] section, add a new section for the parent key of the value. Then add the key value below it, save it, and run devenv.exe with /log. The pkgdef loader will log all of the additional writes to that value, along with the path to the offending pkgdef.

In this example, we caught the blog.pkgdef file writing to the value “foo” under “$RootKey$\MyExtension”. The next step is to determine why and whether this needs to change (be sure to put devenv.pkgdef back the way you found when you’re done).

Summary

This post has described several tactics for troubleshooting pkgdef issues. The most basic of these is to use /log, along with a trick for forcing PkgDef Management to rebuild the pkgdef cache. You may also find that the PkgDef Editor extension is helpful when editing pkgdef files.

Bill Weinberger: Developer, Visual Studio Platform

Bill has been with the VS Platform team for about two years, and has more than a few previous years of software industry experience working on IDEs and vertical applications. For Visual Studio 2010, he was a key contributor to PkgDef Management.

Creating and Sharing Project & Item Templates

Aaron Marten — Thu, 04 Mar 2010 18:01:00 GMT

One of the great new features we added in Visual Studio 2010 is the ability to easily find and consume online Project and Item templates without leaving the New Project/Item dialog. What may not be so obvious is how to go from a piece of code you want to share to a template contained in a VSIX file that can be uploaded to the Visual Studio Gallery or shared with others in your organization.

This post describes two ways (one quick and simple, the other for more complex situations) to create a VSIX file that contains your shareable code templates.

Quick, (mostly) Automatic Way: Export Template as VSIX

In a series of posts on Visual Studio 2010 Beta 1 (Part 1, Part 2, Part 3, Addendum), Pedro Silva walked through the process of using the standard Export Template wizard that has shipped in Visual Studio for several releases in combination with the VSIX Explorer tool or the VSIX Project template in the Visual Studio SDK to package up your template. While this does the job, it seemed like a few too many steps for something that should be straightforward.

To make this process much simpler, we recently published a new Export Template as VSIX wizard that will guide you through the process of turning an existing project into a VSIX file containing your template. After downloading the Export Template as VSIX wizard from the Visual Studio Gallery website or the Extension Manager dialog, you will find a new option on the File menu in Visual Studio 2010 for “Export Template as VSIX…”. This will bring up the Export Template as VSIX Wizard, which will allow you to configure options for both the template and the VSIX file that will contain it.

Longer, (mostly) Manual Way: Template Project + VSIX Project

While this is the ideal way to quickly share some starter code with others, it is not ideal for all situations where you’re creating a template. For example, you may be building a series of templates in conjunction with a VSPackage or editor extension. What if you are making frequent changes to the template files? What if you wish to keep the template source files in a version control system? What if you need to make a customization to the templates or the VSIX container not permitted by the Export Template as VSIX wizard?

This is where the Visual Studio SDK comes in to help. In the Visual Studio 2010 SP1 SDK, we’ve included project templates for building project and item templates. (Yes, we’ve created templates for templates.) If you go to the Extensibility node under Visual C# or Visual Basic in the New Project dialog, you’ll find two new templates (for either a project template or an item template). Let’s walk through the process of creating and packaging a C# Project template using these new templates in the Visual Studio SDK.

Walkthrough: Packaging a template with the Visual Studio SDK

First, we'll create a project template project which generates a zip file for a single template. Then, we'll create a VSIX project to contain and deploy the generated project template.

Open the New Project dialog to create a new “C# Project Template” from the Extensibility category called “MyTemplate”. There are a few interesting things to note about the generated project:
- The .vstemplate file has a Build Action of “VSTemplate”. The .cs, .csproj, and .ico files have a Build Action of “None”. Since this project is meant to build a .zip file, not a .dll or .exe file, the code files are not compiled or treated as code by the build targets.
- If you open Class1.cs or ProjectTemplate.csproj in the text editor, you’ll see that there are several VSTemplate parameters ($safeprojectname$, $guid1$, etc…) that will be replaced when the template is instantiated.
- The files to include in the zip file are discovered at build time by reading the .vstemplate file. Any files not specified in this file will not be included in the template zip file.
Build the project. Note that a .zip file is created for you in a subdirectory of the project output folder. (In our example, the template builds to ProjectTemplates\CSharp\1033\MyTemplate.zip.) The subdirectory in the output folder is determined by looking at a few things at build time:
- The “Type” attribute in the .vstemplate file root node. Project templates go under “ProjectTemplates”. Item templates go under “ItemTemplates”.
- The “Language” part of the path (“CSharp” in our example) is determined by the <ProjectType> node in the .vstemplate file.
- The next part of the sub path is optional (and null by default). This is the OutputSubPath. This can be used for placing the template in a sub-node (e.g. Windows, Web Silverlight) in the New Project dialog. Since we’re building a template for targeting Windows, let’s specify this additional piece of metadata in the MyTemplate.csproj file. (You can edit the file by right clicking the project node and choosing “Unload Project”. Then right click the project node again and choose “Edit MyTemplate.csproj”.)
```
<VSTemplate Include="MyTemplate.vstemplate"> <OutputSubPath>Windows</OutputSubPath></VSTemplate>
```
- The “1033” in the path is the LCID of the template. The LCID for English (US) is 1033 and this is the default. To change the LCID (for example to 1041 for Japanese), you must edit the MyTemplate.csproj to the following:
```
<VSTemplate Include="MyTemplate.vstemplate"> <OutputSubPath>Windows</OutputSubPath><Culture>1041</Culture></VSTemplate>
```
- Finally, the name of the zip file is taken from the name of the project specified in the New Project dialog.
The project we just created only builds a zip file for you. It does not build a VSIX file, nor does it set up the template for debugging in Visual Studio. To do that, add a new VSIX Project to your solution and call it “MyTemplateSetup”. (You can find the VSIX Project template also on the Extensibility node in the New Project dialog.)
When the VSIX project is created, you should see the editor for your source.extension.vsixmanifest file appear. Click the “Add Content” button to specify that the template file you created in steps 1-2 should be included in the VSIX file built by this project.
- Select “Project Template” for the content type
- For the source, select “Project” and then choose the “MyTemplate” project.
- Click OK
Save and close the VSIX manifest editor
Right click the “MyTemplateSetup” project and select “Set as StartUp Project” to debug your template in the Visual Studio Experimental instance.
Press F5 to start debugging (or CTRL + F5 to launch without the debugger).
Show the New Project dialog in the Visual Studio and see your template listed under “Visual C# \ Windows" (if you added the OutputSubPath from step 2).

There are a few other interesting points about the support in the SDK for building templates:

Multi-project templates are supported
If you are building a collection of templates, you can include them all in one VSIX file by repeating the steps above (skipping step 3).

While not as simple as the “Export Template as VSIX” wizard, this technique allows you to build templates and deliver them using the VSIX format while still keeping control over the template source files.

Aaron Marten - Developer, Visual Studio Platform

Short Bio: Aaron has been on the Visual Studio team for 6 years with a focus on extensibility. For Visual Studio 2010, Aaron worked on the Extension Manager and the Visual Studio SDK. In addition to contributing to the Visual Studio blog, he also writes about extending the IDE on his own blog at http://blogs.msdn.com/aaronmar.

Troubleshooting Extensions with the Activity Log

Visual Studio Blog — Wed, 24 Feb 2010 10:15:00 GMT

One of the most powerful tools for troubleshooting issues that involve Visual Studio extensions is often overlooked, even though it has been around for quite some time (since VS 2005). Anyone wondering what Visual Studio is doing with their VS Package, Extension, MEF Component, or pkgdef file should ask the IDE for an activity log. In this article, I will show you not only how to generate an activity log file for Visual Studio, but also highlight some of the things you can find in it.

It’s important to note that this applies not only to the Visual Studio 2010 IDE, but also to applications built using the Visual Studio 2010 Shell (Isolated) (or Integrated). All of the examples will assume the case of Visual Studio running under 32-bit Windows 7. For other cases, substitute the appropriate file locations and names and registry root key.

Creating the Activity Log

This is as easy as it sounds. Here is the magic incantation required to generate a visual studio activity log file:

In this case, I’ve started a command prompt and navigated to the folder where the Visual Studio executable is installed before typing “devenv /log”.

The same command could also be given:

from the Visual Studio Command Prompt (2010)
using the full path to the executable ("C:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE\devenv.exe") from either a command prompt under Start - Accessories or in the Start – Run dialog
on Windows 7, just by hitting the Windows key and typing “devenv /log” in the search box.

Finding the Activity Log

If “/log” is specified without adding an output path, the file is written to

%APPDATA%\Microsoft\VisualStudio\10.0\ActivityLog.xml

%APPDATA% resolves to “C:\Users\user\AppData\Roaming”

In previous releases of Visual Studio, there was a required parameter to /log that specified the full path for the output file. In VS 2010, this path is optional. You might find it useful to direct the log file to an easier to find location, such as the desktop:

devenv /log c:\users\user\desktop\activitylog.xml

Reading the Activity Log

Once you have reached the point in Visual Studio that you are trying to troubleshoot, it’s a good idea to close Visual Studio. Otherwise, it will continue to write to the log while you are trying to read it.

Notice that the log file is generated as XML. When Visual Studio starts writing the log, it also writes a corresponding XSL file next to the XML file that makes it easy to read in Internet Explorer. Go ahead and browse to the file’s location and double-click on it.

At the top of the file is a summary of how many lines of “infos” (sic), “warnings”, and “errors” are listed. Below that are the actual log items, which have up to 7 columns of information.

column	description
#	sequential item number
Type	blank for information, “Warning” (highlighted in yellow), or “Error” (highlighted in red)
Description	the activity, which may optionally include a registry or file path
GUID	associated GUID, typically for a VS Package
Hr	HRESULT value that may be useful for troubleshooting
Source	module writing the log item
Time (UTC)	timestamp for the item in UTC (not local) time

Activity Log Items

The activity log is full of more information than can adequately be addressed in any detail by a single blog post. However, several activities are worth noting:

Version of Visual Studio and .NET Framework
Configuration and state information about the pkgdef cache
If the pkgdef cache is found to be out-of-date, each discovered pkgdef file is listed, as it is parsed and loaded
Each VS Package that is loaded, including success and failure
Each VS Extensions loaded through the Extension Manager and whether it is enabled
Each MEF Component loaded and whether it came from the cache
Each category exported by the Profile manager

Summary

Those are the basics for creating, finding, and reading the Visual Studio Activity Log. Hopefully, this will give you a powerful tool for troubleshooting issues with VS Packages, VS Extensions, MEF Components, and pkgdef files. Try running Visual Studio with /log and see what useful insights you gain into what Visual Studio is doing.

Bill Weinberger: Developer, Visual Studio Platform

Bill is a relative newcomer to Microsoft, but has many years of software industry experience working on IDEs and vertical applications. For Visual Studio 2010, he was a key contributor to PkgDef Management.

MSBuild Task Factories: guest starring Windows Powershell

Andrew L Arnott — Sat, 20 Feb 2010 08:00:00 GMT

One of the cool new features of MSBuild 4.0 is the extensible task factory. Task factories allow you to include scripts directly in your project file (or an imported .targets file) and have those scripts parsed and executed by your favorite interpreter. Those scripts might even be C# or VB.NET code snippets that get compiled into assemblies and executed on-the-fly during the build. This significantly lowers the bar to doing specialized work in your build for which there is no built-in MSBuild Task, since you don’t have to check into your source control repository a precompiled .dll with your custom task any more. You may still want to do that for performance reasons or for the design-time experience of writing MSBuild tasks in C# and get all the C# Intellisense that you only get in a C# project, but for short tasks, “inline tasks” that are built and executed on-the-fly may be just the ticket you need.

MSBuild 4.0 ships with C#, VB.NET and XAML task factories built-in, so you can define a custom task in C# or VB.NET inline today. But writing your own task factory will allow you to write inline tasks in Perl, Python, or in this case… Windows Powershell script.

Consider, for the sake of example, that there is no MSBuild task that sends an email at the conclusion of a build. Fixing that with a custom MSBuild task, compiled into a .dll, seems a bit heavyweight. But defining that task right there in your project file is easy. Here’s how you might write a Powershell inline task using the Windows Powershell task factory. Notice below how we first define the task in terms of the code it executes and its input and output parameters. Then in a standard MSBuild Target we invoke that inline task as we would any other MSBuild task.

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <UsingTask
    TaskFactory="WindowsPowershellTaskFactory"
    TaskName="SendMail"
    AssemblyFile="$(TaskFactoryPath)WindowsPowershellTaskFactory.dll">
    <ParameterGroup>
      <From Required="true" ParameterType="System.String" />
      <Recipients Required="true" ParameterType="System.String" />
      <Subject Required="true" ParameterType="System.String" />
      <Body Required="true" ParameterType="System.String" />
      <RecipientCount Output="true" />
    </ParameterGroup>
    <Task>
      <![CDATA[
        $smtp = New-Object System.Net.Mail.SmtpClient
        $smtp.Host = "mail.microsoft.com"
        $smtp.Credentials = [System.Net.CredentialCache]::DefaultCredentials
        $smtp.Send($From, $Recipients, $Subject, $Body)
        $RecipientCount = $Recipients.Split(';').Length
        $log.LogMessage([Microsoft.Build.Framework.MessageImportance]"High", "Send mail to {0} recipients.", $recipientCount)
      ]]>
    </Task>
  </UsingTask>

  <PropertyGroup>
    <BuildLabEmail>buildlab@yourcompany.com</BuildLabEmail>
    <BuildRecipients>interested@party.com;boss@guy.com</BuildRecipients>
  </PropertyGroup>
  
  <Target Name="Build">
    <SendMail From="$(BuildLabEmail)" Recipients="$(BuildRecipients)" Subject="Build status" Body="Build completed">
      <Output TaskParameter="RecipientCount" PropertyName="RecipientCount" />
    </Add>
  </Target>
</Project>

This project would build, and send a built completion email to recipients determined by the project itself. The only assembly you need is the Windows Powershell task factory itself, which can be reused for all your projects that include inline Windows Powershell scripts.

Note that the inline task above will not run without the task factory .dll that it points to, which in this case is not shipped with VS2010. The Windows Powershell task factory is available as a sample task factory on the MSDN Code Gallery. Feel free to check it out, and give feedback. It’s just a sample, so all the “no guarantees for fitness to any particular task” limitations apply. But you get the source code, so you can tweak it or file bugs if you wish.

How VSIX extensions are discovered and loaded in VS 2010

Visual Studio Blog — Fri, 19 Feb 2010 10:00:00 GMT

VSIX is the new technology used for deploying extensions in Visual Studio 2010. The primary goal of this new technology is to encourage extension creation and consumption by easing the management (“management” meaning Browsing/Installing/Uninstalling/Enabling/Disabling) of Visual Studio extensions. To take full advantage of the VSIX installer for deploying your extensions, it helps to know a little bit more about how Visual Studio decides which extensions to load.

Dmitry Goncharenko provided a good high-level overview of how these VSIX extensions are discovered and loaded in his post Bootstrapping of VS packages and VSIX extensions in VS2010. Let’s now take a more in-depth look at how this process works.

An extension consists of:

an extension.vsixmanifest file, which contains metadata about the extension
any additional files that represent the extension content. This could include MEF assemblies, VS Package assemblies, VS Template ZIP files, PkgDef files, etc..

The simplest vsix extension would contain only the extension.vsixmanifest file, though that would admittedly be a very uninteresting extension.

Extension Discovery

In accordance with the goal of simplicity, a VSIX extension install consists of only copying the extension files into one of a few well-known locations. These locations are defined in the “Master PkgDef” file, located at <VsInstallRootFolder>\Common7\IDE\devenv.pkgdef and pictured below.

The relevant values are described below.

Variable	Description
ApplicationExtensionsFolder	The root folder under which machine wide VSIXs are deployed. (This is set as <VsInstallRootFolder>\Common7\IDE\Extensions)
UserExtensionsRootFolder	The root folder under which user specific VSIXs are deployed. (This is set as %LocalAppData%\Microsoft\VisualStudio\10.0\Extensions)
PkgDefSearchPath	A list of additional folders where extensions will be searched for. The name for this property was originally defined by the PkgDef subsystem. This list is shared with vsix extensions so that any extensions that contain .pkgdef files will be properly loaded. Note that this includes ApplicationExtensionsFolder.

Upon initialization, the Extension Manager service, SVsExtensionManager, will search the above locations for extension.vsixmanifest files. The PkgDefSearchPath folders are searched first, followed by the UserExtensionsRootFolder.

Extension Loading Rules

At this point, each extension must pass a few trials before being considered installed by the Extension Manager. Before diving into the details, here’s a quick summary of these:

The extension.vsixmanifest XML conforms to the XSD.
The extension has not been marked for deletion.
The extension’s identifier cannot conflict with any other previously discovered extensions.

First, if the extension.vsixmanifest XML does not conform to the VSIX manifest XSD schema, it is ignored. If the manifest XML passes schema validation, then it will be deserialized into an object model in memory. Second, the Extension Manager needs to verify that the extension is not marked for deletion. Before going any further, it would be helpful to discuss what exactly this means.

If you’ve uninstalled an extension through the Extension Manager dialog in Visual Studio, you may have noticed that the uninstall occurs extremely fast. This is because the extension is only marked for deletion at that time. On a subsequent initialization of the Extension Manager (the next time Visual Studio or the VSIX Installer are launched), all of the pending deletions are cleaned up on a background thread *after* all installed extensions have been discovered. Therefore, any extension that is marked for deletion should be discarded and no longer considered installed.

Third, if the extension contains the same ID as another extension that has already been discovered, it will be discarded. This is where the search order becomes important. The UserExtensionsRootFolder is searched last in order to give precedence to machine wide extensions when an ID conflict is encountered.

Once an extension has passed these checks, it is considered “installed” by the Extension Manager service. Figuring out whether an extension is not installed because of one of the above reasons is easy since the Extension Manager logs this information to the Visual Studio activity log. The activity log can be enabled by running the Visual Studio process (<VsInstallRootFolder>\Common7\IDE\devenv.exe) with the ‘/log’ switch, as follows:

devenv.exe /log <path_to_log_file>

The Mechanics of Enabled/Disabled Extensions

So your extension is successfully “installed”, but how does the Extension Manager determine whether it’s “Enabled”? The answer depends upon where your extension is installed. Extensions installed to any directory in the PkgDefSearchPath list of folders are always enabled. Extensions installed to the UserExtensionsRootFolder path must be individually enabled through a list maintained in the HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\10.0\ExtensionManager\EnabledExtensions registry key. The Extension Manager Install API, used by the extension install dialog as well as the VSIX installer, will write the entry in the EnabledExtensions key for any newly installed extension so that extensions installed in this manner are automatically enabled. You’ll notice that if you manually install an extension by copying the extension files to a subfolder in the UserExtensionsRootFolder path, it will be disabled at first because the corresponding entry in EnabledExtensions has not been added. Enabling the extension can also be accomplished through the Extension Manager dialog.

Lastly, extensions in the UserExtensionsRootFolder path will all be disabled when running Visual Studio as an administrator, if the following option is not checked under Tools->Options->Environment->Extension Manager

This option was likely the most common culprit for why users (particularly administrators running WindowsXP) found that their extensions were not enabled in Beta2 and prior builds of Visual Studio, since the default value for the option was ‘False’. Due to the frequency with which customers ran into this problem, we’ve changed the default value for this option to ‘True’. Note that the Extension Manager dialog provides a warning if you’re running Visual Studio elevated, but do not have this option checked.

When in doubt about why an extension does not seem to be loaded or enabled, you should consult the Visual Studio activity log, which will output various diagnostics during the loading process. You may also want to check out the following posts related to extension loading:

Mariano Blanco: Developer, Visual Studio Platform

Mariano started in the Visual Studio Ecosystem team at Microsoft in 2007. He now works on the Visual Studio Platform Extensibility team and is responsible for the Extension Manager API and the VSIX installer tool shipping in Visual Studio 2010.

CodeBlog: Writing a Blogging Extension for Visual Studio 2010

Visual Studio Blog — Mon, 15 Feb 2010 22:15:00 GMT

Have you ever wanted to quickly share a code sample to Twitter or your blog without leaving Visual Studio? Steve Apiki walks through how to create an extension for Visual Studio 2010 that does just that.

Walkthrough: http://www.devx.com/VS_2010/Article/44073

His walkthrough touches on a number of extensibility options inside Visual Studio 2010 such as:

How to add a command to a context menu
How to create text adornments with the new VS 2010 Editor
How to create a Tool Window and add WPF content to it
Managed Extensibility Framework (MEF) basics
Using XML-RPC.NET to post to Twitter

Enjoy!

Announcement: Unpublishing Extensions from Beta 2 to RC

Visual Studio Blog — Thu, 04 Feb 2010 00:47:00 GMT

UPDATE 2/8: I forgot to mention a change to the VSIX file format in the Release Candidate that might impact your extensions. The valid <Edition> values (under <SupportedProducts>) have been updated to better reflect our SKU branding. The only valid values for RC and RTM are: IntegratedShell, Pro, Premium, Ultimate, Express_All, VBExpress, VCSExpress, VWDExpress, VCExpress. We have removed VST_All, Pro_All, VSTT, VSTD, and VSTDB from the list of supported values. If your extension lists any of the removed values, you will need to update your VSIX manifest and reupload your extension. If this is not done, your extension will not show up in the Extension Manager or the New Project Dialog since SKU-filtering is applied. Also note, that you only need to include the lowest common denominator supported SKU. For example, if your extension works in Pro, you only need to list "Pro" under the <Edition> element, as Premium and Ultimate are supersets of Pro and will pick up Pro-supported extensions.

When the public Release Candidate (RC) is released later this month, we will be unpublishing all Visual Studio 2010 Beta 2 extensions that are hosted on the http://www.visualstudiogallery.com. We do this because we want to ensure that all extensions are tested and work on the latest release (RC) so that users aren’t treated to numerous errors either when installing or using the extension. This same process was used to convert Beta 1 to Beta 2 extensions. The extension author will have the responsibility of testing and republishing the extension.

FAQ

Q: Will my VS 2008 or VS 2005 extensions be unpublished?
A: No, this will only affect VS 2010 extensions.

Q: Will I need to rebuild my extension and then reupload?
A: Possibly. There have been a few breaking changes in the extensibility APIs from Beta 2 -> RC, so you’ll need to verify that your extension still behaves correctly. If bugs are found, this will require a rebuild. If everything works as expected, a rebuild is not necessary.

Q: How do I republish my extension?
A:

Navigate to http://www.visualstudiogallery.com and sign in
Click on “My Contributions” on the top navigation bar
You’ll see the text “(Unpublished)” next to the title of any contributions that have been unpublished
Simply click on the extension and select “Publish”

Q: Will I have to do this for every major VS release?
A: This will need to be done once more when VS 2010 RTM is released. We’re still examining how best to manage this from release to release (both for Service Packs and next versions). If this process is necessary to repeat, we will look to provide a tool or an automated way to move extensions over.

Q: Will my extension work in Beta 2?
A: After two weeks, we will be disabling online extension manager access for VS 2010 Beta 2. This is because extensions that have been ported to RC may not work on Beta 2 anymore.

Please let comments if you have any additional questions about this process.

Weston Hutchins – Program Manager, Visual Studio Shell Team
Short Bio: I started at Microsoft as an intern in 2005 and have been working in Visual Studio ever since. I’m currently a PM on the VS Shell IDE team and work on the core IDE UI and services as well as the Extension Manager and http://www.visualstudiogallery.com integration. Prior to my current duties, I was the SKU manager for the Visual Studio Express products.

How to read/write the new Visual C++ project properties

Andrew L Arnott — Fri, 15 Jan 2010 05:00:00 GMT

Visual C++ 2010 introduces several new project and tool properties, and deprecates some old ones. If you’re writing a project template or Visual Studio extension that needs to programmatically read and write the new properties, you will find that these properties are not available on the standard VCConfiguration, VCCLCompilerTool, etc. set of interfaces. These are COM interfaces and cannot be changed. Rather than create new interfaces for the new properties, we’ve introduced a single new interface that will provide access to all project and tool properties: IVCRulePropertyStorage.

Before we dive into IVCRulePropertyStorage, you should take a few minutes to learn about Visual C++ "Rule” XAML files, as Pavan describes in his post: Platform Extensibility – Part 1.

One new property in Visual C++ 2010 is TargetExt, which specifies the filename extension of the primary output of a Visual C++ project. This property isn’t available on VCConfiguration. Let’s read and write it using IVCRulePropertyStorage assuming you’ve got a DTE object for the project. While we’re in there, we’ll read and write a few other properties at the project and file level. I’ve written this code as it might be seen in the IDE Macro Editor. You can try copying and pasting this code into the Macro Editor yourself and running it while you have a new C++ console application open in the IDE.

    Public Sub RulePropertyAccess()
        Dim vsPrj As VSProject = CType(DTE.Solution.Projects.Item(1).Object, VSProject)
        Dim vcproj As VCProject = vsPrj.Project.Object
        Dim vcconfigs As IVCCollection = vcproj.Configurations
        Dim vcfiles As IVCCollection = vcproj.Files
        For Each vcconfig As VCConfiguration In vcconfigs
            ' Start by accessing a configuration-level property: TargetExt
            ' The "ConfigurationGeneral" string comes from the 
            ' %PROGRAMFILES%\msbuild\Microsoft.Cpp\v4.0\1033\general.xml
            ' file's <Rule Name="ConfigurationGeneral"> tag.
            Dim generalRule As IVCRulePropertyStorage = vcconfig.Rules.Item("ConfigurationGeneral")
            Dim oldExtension As String = generalRule.GetEvaluatedPropertyValue("TargetExt")
            generalRule.SetPropertyValue("TargetExt", ".dll")
            Debug.Print("TargetExt before: {0} and after {1}", oldExtension, generalRule.GetEvaluatedPropertyValue("TargetExt"))

            ' Now let's access a tool-specific property at the project level: WarnAsError
            ' This property isn't new, so it's available both through VCLinkerTool and IVCRulePropertyStorage
            ' Note however that its MSBuild property name does not match its name on the interface.
            Dim vctools As IVCCollection = vcconfig.Tools
            Dim cl As VCCLCompilerTool = vctools.Item("VCCLCompilerTool")
            Debug.Print("VCCLCompilerTool::WarnAsError reports {0}", cl.WarnAsError)
            Dim clRule As IVCRulePropertyStorage = cl ' we only need to QI for this interface on the same object
            clRule.SetPropertyValue("TreatWarningAsError", Not cl.WarnAsError) ' invert the value
            Debug.Print("VCCLCompilerTool::WarnAsError now reports {0}", cl.WarnAsError)

            ' Now let's set a property for a very specific .cpp file.
            Dim stdafxFile As VCFile = vcfiles.Item("stdafx.cpp")
            Dim stdafxFileConfigs As IVCCollection = stdafxFile.FileConfigurations
            Dim stdafxFileConfig As VCFileConfiguration = stdafxFileConfigs.Item(vcconfig.Name)
            Dim fileCL As VCCLCompilerTool = stdafxFileConfig.Tool
            Debug.Print("StdAfx.cpp VCCLCompilerTool::InlineFunctionExpansion reports {0}", fileCL.InlineFunctionExpansion)
            Dim fileCLRule As IVCRulePropertyStorage = fileCL
            fileCLRule.SetPropertyValue("InlineFunctionExpansion", "OnlyExplicitInline")
            Debug.Print("StdAfx.cpp VCCLCompilerTool::InlineFunctionExpansion reports {0}", fileCL.InlineFunctionExpansion)
        Next
    End Sub

So you see that IVCRulePropertyStorage provides very simple property read/write access. And exactly where those properties are read from or written to depends on where you acquired the IVCRulePropertyStorage object. As shown above, you can get this object from the VCConfiguration, a VC*Tool at the VCConfiguration level, or a VC*Tool at the VCFileConfiguration level. Not shown above is that you can also get this object from the VCPropertySheet::get_Rules collection, similarly to how we show above using VCConfiguration::get_Rules. As you might expect, IVCRulePropertyStorage objects obtained from VCPropertySheet objects will read and write to that property sheet instead of the project.

The IVCRulePropertyStorage interface can only be used to read and write properties for which a Rule XAML file exists that is imported into the project. If your software requires custom properties that do not exist in a Rule file, you need to create a Rule file that describes those properties and then import that file into your project, as described in Pavan’s Platform Extensibility – Part 1 and Part 2. Why do we require these steps? Because it turns out that project properties have many attributes, such as where they should be persisted in the file, in which file (project or .user file), whether they are project properties or metadata on items or item definitions, etc. etc. The Rule file allows you to capture all that per-property detail so that your code that invokes IVCRulePropertyStorage can be free of these implementation-specific details.

Every single property available in the Visual C++ Property Pages dialog has a Rule file associated with it already, guaranteeing you convenient programmatic access to read or write any property you find there.

A note on debugger properties

There are a couple of interesting points to note with regard to properties that configure the debugger.

Debugger properties are stored in the project user file (*.vcxproj.user) rather than the project itself. This doesn’t require any special coding on your part—you just acquire the IVCRulePropertyStorage object from VCConfiguration the same as you would for other properties. The Rule.DataSource tag in the debugger_*.xml rule files tell the IVCRulePropertyStorage to persist to the .user file instead of the project file so that you don’t have to worry about that detail.

In Visual C++ 2008 and earlier, debugger properties were accessed using VCDebugSettings. This interface had only a small set of properties, many of which were overloaded to control several different debuggers (local, remote, web browser, etc.) so these properties could not be set for a particular debugger without risk of impacting other debuggers. In Visual C++ 2010 we’ve isolated each debugger’s properties so they are independent of one another. The VCDebugSettings interface is still present in Visual C++ 2010, but deprecated since it did not have the isolated set of properties per-debugger. For this reason, we highly recommend you use IVCRulePropertyStorage for getting and setting debugger properties for your Visual C++ 2010 IDE extensions. As with any other properties, you can discover the set of available properties for each debugger and their names and possible values by inspecting these files: %ProgramFiles%\msbuild\Microsoft.Cpp\v4.0\1033\debugger_*.xml

Codecast interviews about the Editor and Extensibility

Visual Studio Blog — Sun, 20 Dec 2009 03:12:00 GMT

Happy holidays everyone!

Chris Granger and I met up with Ken Levy the other day to talk about the new Editor and VS Extensibility.

Ken is responsible for the code cast interviews at code magazine. Chris and I sat down with Ken to discuss the Editor, the SDK, the Extension Manager, VSIX and some of the cool new things we’re shipping in Visual Studio 2010.

The code cast links are below… Enjoy! :)

Visual Studio Extensibility (SDK, Extension Manager)

Visual Studio Editor

Quan To – Program Manager, Visual Studio Platform Team
Short Bio: Quan is responsible for the Extension Manager and Visual Studio SDK. Quan has been with Microsoft for over ten years and has also spent time working on the Tablet PC Team and the Visual Studio Deployment team.

What's A PkgDef? And Why?

Visual Studio Blog — Fri, 18 Dec 2009 12:58:00 GMT

A .pkgdef file is way to encapsulate application configuration information in an easily editable, distributable, and deployable form. It was introduced in Visual Studio 2008 SP1 to support the configuration of Isolated Shell applications. In Visual Studio 2010, .pkgdef files take on a more expanded role and are much more integrated into both the IDE and the Shell (Integrated and Isolated). This article will briefly describe the .pkgdef format and introduce the scenarios where it is used in VS 2010. Future posts will go into more detail about particular scenarios.

Here is a portion of a .pkgdef file that registers the Extension Manager (which is written as a VS Package) with the IDE:

It looks a lot like a .reg file as exported from the Registry Editor. There is one key difference: the root of the registry key (e.g., "HKEY_LOCAL_MACHINE\Software\Microsoft\VisualStudio\10.0") has been abstracted into the token "$RootKey$". This, and several other tokenized values for registry keys and paths, allows a given .pkgdef file to be reusable for multiple applications and portable to any machine.

This example also demonstrates why this format was originally called a "pkgdef". A .pkgdef file can be used to define the registration of a package. Now that this format is used for many other registration and configuration tasks, there was some talk of changing the name and extension to something more generic. We decided that the pkgdef appellation was just as good as anything else. Like most computer terminology, the first name seems to have stuck.

Let's go back and look at that first application of the .pkgdef file to configure Isolated Shell applications in VS 2008 and see what it involved. An Isolated Shell application reads its configuration data from at least four .pkgdef files.

file	description	location
MyVSShellStub.pkgdef	created by the New Project Wizard when the Isolated Shell application project is created. The master pkgdef configuring the application’s pkgdef environment.	next to MyVSShellStub.exe
MyVSShellStubApplication.pkgdef	created by the New Project Wizard when the Isolated Shell application project is created. Contains basic values for configuring and branding the Isolated Shell application	in Extensions below MyVSShellStub.exe
MyVsShellStub.pkgundef	also created by the wizard. Used to remove (or undefine) packages that are configured as part of the Isolated Shell redistributable installation (see BaseConfig.pkgdef)	next to MyVSShellStub.exe
BaseConfig.pkgdef	part of the Isolated Shell redistributable installation. Contains configuration information for the core features of the Shell, such as the Editor and Designers and the other parts of the IDE	in ShellExtensions\Platform beneath C:\Program Files\ Microsoft Visual Studio X.0\ Common7\ IDE
*MyPackage.pkgdef**	created for any VS Package projects that are created as part of the Isolated Shell application	in Extensions below MyVSShellStub.exe (and elsewhere as defined by PkgDefSearchPath)

Notice that that configuration and registration information originates from both the application developer and Microsoft. All of these values have to be merged into a common location specific to the application so that the Shell and the Packages in the application can retrieve them. In VS 2008, this was done during installation of the Isolated Shell application by running the application executable with the "/setup" switch (as a setup Custom Action). This caused the Shell to read all of the .pkgdef files and build a new configuration hive for the application in the registry under HKEY_LOCAL_MACHINE. During the development and test cycle of an Isolated Shell application, the "/ranu" ("run as normal user") switch was used to create a test hive under HKEY_CURRENT_USER, in order to avoid issues with having Administrator access to the registry.

Visual Studio 2010 makes the .pkgdef load and merge operation a normal part of initialization sequence for both the Shell and the IDE. It also locates the target of the merge, known as the config (or configuration) cache, under HKEY_CURRENT_USER (next to the user settings for the application, but with a "_Config" suffix). This eliminates the need to run the merge as part of setup and eliminates the need for the "/ranu" switch during testing. It also enables an additional scenario: the Extension Manager.

The Extension Manager feature allows users to download extensions to the Visual Studio IDE and integrate them without having to run setup. Extensions that are written as VS Packages that must register with the IDE do so using a .pkgdef file. Simply restarting the IDE after the extension is installed (by unzipping its VSIX file) and enabled causes the IDE to build a merged registry hive out of the values that were written to HKEY_LOCAL_MACHINE during Visual Studio setup and the values in .pkgdef files found on disk. The user is not required to take any extra steps or have Administrator privileges.

You may notice that in the case of the Isolated Shell application all of the configuration values come from .pkgdef files. But in the case of the Visual Studio IDE some of the values come from HKEY_LOCAL_MACHINE. In the latter case, VS continues to use the HKLM hive in order to support some compatibility and servicing scenarios. But we plan to continue moving more configuration values out of the registry as we are able.

The .pkgdef file was introduced in VS 2008 to allow a more modular way to deploy configuration values for the Visual Studio Shells. Improvements in .pkgdef file loading and merging in VS 2010 have made the use of .pkgdef files more automatic and enabled the setup-less installation of Visual Studio extensions.

In future posts, I plan to describe in more detail how and when VS decides to refresh the config cache, why a .pkgdef file might not be loaded and how to debug that, and the purposes of the various .pkgdef files. In the meantime, Aaron Marten and Dmitry Goncharenko have already written several excellent related posts, some of which I have already referenced above:

You may also want to read an Introduction to the Visual Studio Shell or view a recent Presentation about the Shell in VS 2010.

Bill Weinberger: Developer, Visual Studio Platform

Upcoming VS Platform MSDN Webcasts

Visual Studio Blog — Tue, 01 Dec 2009 17:20:00 GMT

[Update: The Introduction to Visual Studio 2010 Extensibility has been moved to 12/16 @ 10 a.m. Please update your calendars to reflect this change.]

I wanted to announce two upcoming MSDN Webcasts that will be presented by Visual Studio Platform PMs, Weston Hutchins and Chris Granger. Both of these are introductory level talks focused on extending Visual Studio 2010. We’ll be presenting some slides, showing off some cool demos, and answering some Q&A at the end, so please join us by clicking on the Attendee Registration links below!

I Want Coloring: A scenarios based look at the new Editor.

When: Wednesday, December 09, 2009 10:00 AM Pacific Time (US & Canada)
Duration: 60 minutes
Presenter: Chris Granger, Program Manager, VS Editor
Attendee Registration: http://msevents.microsoft.com/CUI/EventDetail.aspx?EventID=1032434989&Culture=en-US

While many of you may know that Visual Studio 2010 comes with a new WPF based, extensible editor, do you know why you should care? We will take a look at the new editor by examining a series of common scenarios that showcase what you can do with editor extensions. You can think of this as your crash course; you’ll learn some concepts, you’ll see some code, and you’ll walk away with a head full of possibilities.

An Introduction to Visual Studio 2010 Extensibility

When: Wednesday, December 16, 2009 10:00 AM Pacific Time (US & Canada)
Duration: 60 minutes
Presenter: Weston Hutchins, Program Manager, VS Shell
Attendee Registration: http://msevents.microsoft.com/CUI/EventDetail.aspx?EventID=1032434987&Culture=en-US

Want to customize and enhance the out-of-box Microsoft Visual Studio 2010 development environment? Want to build your own Windows Presentation Foundation (WPF) tool window but don't know how to get started? In this webcast, we cover the basics of Visual Studio extensibility and show you how to take advantage of the numerous extension options inside Visual Studio. Additionally, we discuss the new extensibility enhancements in Visual Studio 2010 and how you can take advantage of those enhancements in your application. This is a fun session with plenty of demos, we have something to offer the Visual Studio novice up to the seasoned veteran.

What's new for editor extenders in Beta 2?

Visual Studio Blog — Mon, 23 Nov 2009 23:50:00 GMT

Noah Richards – Developer, Visual Studio Editor Team
Short Bio: Noah has been working on the Visual Studio Editor team since he graduated college two and a half years ago. He maintains a blog, posts sample code for editor extensions, and frequently answers editor-related questions on Twitter.

Editor’s Note: This post was originally published on Noah’s personal blog, which we’d encourage you to follow for additional content about the new VS 2010 editor and its extensibility.

Now that Visual Studio 2010 Beta 2 has been out for about a month, most of you have probably seen it and tried many of its new features. For those interested in writing extensions for VS, we wanted to share a couple of updates around editor extensibility, particularly for people who wrote extensions in Beta 1 and want to upgrade to Beta 2.

1 – No More IEnvironment

If you wrote any code that had classifiers or taggers or various other extensions that take an IEnvironment parameter, you'll be deleting those parameters in Beta 2. IEnvironment had a few historical reasons for being there (back when the editor was a part of a different project and not in Visual Studio yet), but it wasn't really serving a purpose anymore. In Beta 1, all it really did was confuse people and make you type an extra few characters and/or add an FxCop suppression since you weren't using it. This is a small change but a simplifying one. (If you are curious about the one place that did use it for taggers, see #5 below).

2 – Mouse and key processors get more metadata

In Beta 2, mouse and key processor providers take the following metadata; note that some of these were required for mouse or key processors, but now the list applies to both:

Export, like all components
ContentType
Name and Order, so that you can position yourself before or after other known handlers. This is important in cases where you want to preempt whatever normally happens in a certain event.
TextViewRole

Also, somewhat tangentially, the ContentType attribute now applies to any buffer in a view's graph - that's just a fancy way of saying that if you have something like an ASP.NET page that has embedded C#, your key or mouse processors will get loaded if they have [ContentType("CSharp")].

These fixes were necessary to write the triple click extension, which selects a line on triple click (you can find its code on github and its binaries on the VS Gallery). Without the ordering, I couldn't put the mouse handler early enough to work correctly. Also, there were a few bugs in some of the default mouse handlers that have since been fixed.

Note that, unfortunately, the general guidance is to not use keyboard providers. The VS command system and the way components like the editor plug in don't play very well with normal WPF keyboard input, so the short story is that you'll only get keyboard events for key combinations that aren't already bound to a command. Which leads me to the next new thing...

3 – Listening for the creation of IVsTextView adapters (IVsTextViewCreationListener)

We added this as an extension to the VS integration piece of the editor to allow people to listen for the creation of IVsTextView (which is what the underlying IWpfTextView /ITextView are wrapped in for the sake of people who still use the existing VS API). It's effectively identical to IWpfTextViewCreationListener, except that you get an IVsTextView instead of an IWpfTextView when called.

A quick note – if you want to use this extension, you'll need to add a reference to Microsoft.VisualStudio.Editor.dll. It's in the SDK, so that's not a problem, but it isn't a part of any of the standard editor project templates.

The biggest reason we introduced this was for extensions that want to add command handlers to the editor. You could do this in the past, somewhat painfully, by doing the following:

Write an IWpfTextViewCreationListener
The ugly step - listen for the GotAggregateFocus event on the text view and do the remaining steps in that handler. If you skipped this step, the eventually attempt at getting the IVsTextView would fail, since the two objects weren't fully hooked up yet.
With an [Import]ed IVsEditorAdaptersFactoryService, call GetViewAdapter to get the IVsTextView.
Call IVsTextView.AddCommandFilter
...and don't forget to unsubscribe from GotAggregateFocus or use a flag so that you only listen to the first time the event is raised.

With the new event, you just need to:

Write an IVsTextViewCreationListener
Call IVsTextView.AddCommandFilter

If you do want to get the associated IWpfTextView for the IVsTextView adapter, you can do the opposite of #3 above (using GetWpfTextView); the upside, relative to the above list, is that you don't need to worry about initialization being finished. When you get the call in your creation listener, initialization has completed to the point that GetWpfTextView will always succeed.

Because command filters are still not entirely obvious to get correct, I'm working on a template to do this for you. More in general, I'm working on a set of "New Item" templates for the editor, so that you can add new components (or at least a skeleton of a new component) with a couple clicks in an existing project. I haven’t finished these yet, but you can see the work in progress on CommandFilter.cs.

4 – Custom text marker visual definitions

One of the other things missing in Beta 1 was the ability to set the visualizations for text markers (the markers you can create with an ITagger<TextMarkerTag>). There were some built-in marker types, but they were somewhat limited.

In Beta 2, that's now changed, and you can export a MarkerFormatDefinition that looks something like this:

Export(typeof(EditorFormatDefinition))]
[Name("mymarker")]

internal sealed class MyMarkerDefinition : MarkerFormatDefinition
{
    public MyMarkerDefinition()
    {
        this.ZOrder = 1;
        this.Fill = Brushes.Blue;
        this.Border = new Pen(Brushes.DarkGray, 0.5);
        this.Fill.Freeze();
        this.Border.Freeze();
    }
}

And then create a TextMarkerTag with the name "mymarker", and you are all set. Note that you'll probably want some transparency on your fill brush, since the selection is drawn underneath markers.

5 – View tagger provider (IViewTaggerProvider)

In Beta 1, you exported your taggers with an ITaggerProvider. In Beta 2, there is an additional interface you can use called IViewTaggerProvider, which is passed both a buffer and a view in its CreateTagger method. There are a few cases where you may want to use this:

Your tagger needs information specific to a certain view – this may be the case if you are writing an extension that wants to, say, highlight all references in a view that match the reference under the caret. In this case, you need to know the caret position in the view to produce your results.
Your tagger wants to produce different results depending on the view – this is basically the same as #1, but it may help to also think of it in this way. With the highlight references example again, it's possible to have two different views over the same buffer (split window, for example, or the code definition window), where you want each view to show different results for the highlighted references, even though they are displaying the content of the same text buffer.
Your tagger wants to consume other tag information – this is a more complex case that probably deserves its own blog article. Basically, if you have a tagger for type T that consumes, say, classification tags, you want to avoid accidentally including a classifier that is trying to consume tags of type T, or else you'll end up with an ugly recursive loop when trying to get tags. You can sidestep this by providing your tagger with an IViewTaggerProvider and consuming taggers (or classifiers) you get from an IBufferTagAggregatorFactoryService (or IClassifierAggregatorService.GetClassifier that takes a buffer). That way, you are guaranteed that any taggers/classifiers you may consume can't accidentally consume your extension as well.

The downside to #3 is that it is still hairy for other components to safely consume your tagger (that they are using via IViewTagAggregatorFactoryService) to produce tags; if two view-level taggers are each consuming other view-level taggers, you get the same problem as before. As such, any component you make that does this should be created with the understanding that it can't be safely consumed. For any extensions you write, you should probably steer clear of creating view-level taggers that consume a view-level ITagAggregator<ClassificationTag>, for example. In general, it's probably safest to follow this rule:

Never create a tag aggregator using an IViewTagAggregatorFactoryService inside a tagger provided with an IViewTaggerProvider.

...and more

This is not an exhaustive list; these are just the biggest ones I can think of off the top of my head. We’ll continue to post more editor and extensibility content on the Visual Studio Blog and my blog, so stay tuned. And as always, comments are welcome.

- Noah