Having great samples to help you learn about any programming language or paradigm can be very valuable. In my opinion, a good sample can be characterized by:

Being easy to replicate

Having clear steps that guide the reader to replicating the behavior of the sample into their own code base is paramount. Without clear guidance and explanation on how to consume the sample, the sample is much less efficient and may lead to the reader becoming annoyed.

Being self-contained

The sample needs to contain the needed documentation, code comments and simplicity that makes it easy to understand. It must keep the concept count to a minimum to reduce noise.

Linking to additional resources

A sample is not a replacement for full documentation but shows how to implement concepts that can pan multiple sets of documentation. If the reader is interested in knowing more details about the various technologies and concepts used by the sample, links must be made available.

Being able to build and run

It should be possible to clone the sample to your machine, open it in Visual Studio and being able to run and debug effortlessly. Setting breakpoints and inspecting the code is a fantastic way to help understand how the sample works.

New samples

The Visual Studio extensibility team has a notable set of samples for various different aspects of writing extensions. However, they do not adhere to the rules outlined above and we are looking into updating them accordingly and adding new ones as well.

So, we’ve created some experimental samples on GitHub that addresses some pain points we’ve noticed over the years. They are:

  1. Doing options the right way - This sample shows how to correctly specify and consume options for a Visual Studio extension that is both thread-safe and performant.
  2. VisibilityConstraints - This sample shows how to use the <VisibilityConstraints> element in a Visual Studio extension to remove the need to use the ProvideAutoload attribute on a package class.
  3. Protocol Handlers - This sample shows how to associate a URI protocol with Visual Studio and handle the passed in URI. For instance, a link with a custom protocol (such as vsph://anything/I/want) will open Visual Studio and pass the URI to the extension.
  4. Textmate Grammar - This is a sample project that demonstrates how to ship Textmate grammars inside Visual Studio extensions.

Give us feedback

Please help give us feedback on these new types of samples by either commenting on this blog post or, even better, opening issues directly on the samples on GitHub. The more feedback we get, the better the samples get, and we can start writing lots more of them.

Also, what scenarios should the next batch of Visual Studio extensibility samples address?

Comments

Jamie Cansdale

Something I constantly struggle with it knowing when to use the DTE object model, when to use MEF (the IWpf... interfaces) and when to use VS services (SVs.../IVs... etc). Often I end up using a mixture and wonder if there's a better way. Something I'd love to see is a breakdown of the top level DTE methods, with equivalent code that uses MEF or VS services (when available). For example, what is the SVsXXX equivalent of DTE.ActiveWindow? What about using MEF and the IWpfXXX interfaces? Or how would I do the equivalent of: ``` foreach(Command command in dte.Commands) Console.WriteLine(command.Name); ``` ...using VS services. Is there any way to access the list of VS commands via MEF? Does that make sense?

Jamie Cansdale

Mads Kristensen

@Jamie, that is a brilliant idea. I have the same questions dealing with the DTE and it's something I could investigate and document. Thanks for the suggestion!!

Mads Kristensen

Jamie Cansdale

I thought you might. I've noticed a pragmatic sprinkling of DTE usage in your code. It would be interesting to dig a little and find out when it makes sense to use what. You must have the contacts and mandate to crowd source the answers. ;-)

Jamie Cansdale

Comments are closed