The official source of product insight from the Visual Studio Engineering Team
Samples are the primary way that we as developers learn to develop applications for a new platform. We use samples as a starting point to learn about new APIs, we reference them when we hit bugs in our own code and need a comparison, and we share them for others to learn from our discoveries. If a picture is worth a thousand words then a sample is worth thousand pages of documentation. With Visual Studio 2012 we set out to give developers easy access to find and use samples, especially when building applications for Windows 8.
We first looked at the collection of samples we already had, and those we planned to add. It quickly became clear that we needed a better storage and update model. Samples have found many different homes over the years and this led to difficulties in discovering them and problems using them. With the purpose of getting our samples out of the hard to find corners of our websites and into one central location, we created a single site called the MSDN Code Samples Gallery and introduced easy ways to discover and use them in Visual Studio 2012. This post describes our journey.
One of the primary ways samples were released is through software development kits or SDKs. The SDK was used as single vehicle to ship tools, documentation, headers, libraries and samples. Shipping samples with an SDK was convenient for bundling all the tools and assets in one place but you never knew what you were going to get after you installed the SDK. Samples were often laid somewhere on the file system, sometimes in read-only locations like program files, with few hints about where to find the samples or information about what was available. Searching for information about the samples in an SDK before you installed a sometimes large set of content was impossible unless the SDK authors duplicated all their SDK contents online. Updating a sample that was part of an SDK was also a challenge because it meant updating the entire SDK so, needless to say, samples in SDKs were not often updated.
Another popular way samples were published was through individual and team blogs as single samples or packs zipped and stored online. Moving samples out of SDKs and online was a step right direction but it too had limitations. Blogs gave sample authors flexibility to talk more about what the samples do and even update the details over time. However, sample shipped through blogs or team sites were still limited to the discoverability of those sites. Blogs gave the flexibility to push out new updates to samples but users that previously downloaded the sample most likely found it from a Bing search and likely did not see updates unless they were active followers of the blog.
Another challenge with both of these approaches is that samples often required a number of manual steps to ensure they could compile and run on the developer’s machine. Depending on how the sample was packaged and whether you installed the headers and libraries from the required SDK before running the sample you would experience very different results. The usefulness of a sample could also depend on the toolset version you were using and might not have worked on an older toolset version that did not support that particular project type.
The new MSDN Code Samples Gallery brings all Microsoft samples into one site. By dedicating one site to samples we were able to create a richer experience for developers around searching, browsing, and managing useful samples. We also focused on ensuring the samples submitted to the MSDN Code Samples Gallery were high quality to help explain new technologies and jumpstart new projects. All content on MSDN Code Samples Gallery site is searchable so users on the website can search description text for keywords like “file access” or specific APIs like “WriteTextAsync” directly in the solution’s source code. The content is also accessible to search crawlers so users can search through the web site or their favorite search engine. Any search on the MSDN Samples Code Gallery can be refined with filters to focus on a specific technology platform, programming language, development topic, or Visual Studio version.
Each sample page has a rich HTML description intended to provide an overview of the topics covered in the sample as well as instructions on how to get the most from that sample. Sample pages on the site also offer optional forums for Q and A to start a dialog with the sample author or other users. Using the rating and review features provided with each sample page helps the MSDN Code Samples Gallery serve up the most useful samples as well as provides valuable feedback and recognition for the sample authors.
Some problems only need a small amount of code to demonstrate the concept. The MSDN Code Samples Gallery website also displays source for the sample so you can browse and copy the segment of code you need. Other problems are more involved and it helps to run the sample under a debugger to understand exactly what’s going on in the code. When you download the full sample you will always get a project and solution so you can open and run it within Visual studio. If you don’t find the sample you need you can request a new sample or vote on an existing request for Microsoft or the community to create.
Some developers are targeted about their use of samples, only downloading the samples they need, while other users want to have access to a large body of related samples they can go back to over time. To give developers an option to grab a collection of samples we added the notion of a Sample Pack into the gallery website and Visual Studio 2012. Sample packs, like the Windows 8 Consumer Preview Sample Pack, the Visual Studio 2010 C# Sample Pack, and the 101 LINQ Sample Pack are available on the MSDN Code Samples Gallery as a complete set providing a reference collection of samples for a specific technology.
The MSDN Code Samples Gallery site is open for anyone to contribute helpful samples. Contributing a sample is as simple as zipping your solution, uploading it to the MSDN Code Samples Gallery and providing an informative description with technology and topic tags. Our aim was to keep the upload process as simple as possible because after all these are samples and you shouldn’t have to spend more time uploading the sample than you did creating it in the first place. Once you upload your sample we automatically identify your target language(s), Visual Studio version, and repackage it with a community license and an offline copy of your description. We are always looking for high quality code samples so we encourage you to contribute your code sample and give the site a try.
The Samples gallery can be browsed and searched and samples downloaded directly from within Visual Studio 2012. In the File/New Project dialog, you can find them under the Online tab on the left pane:
Downloading a sample from within Visual Studio has a few added benefits. Visual Studio will manage the samples you download and keep a master copy of each sample you download under the new ‘Samples’ node in the ‘Installed’ tab of the New Project Dialog. At the same time Visual Studio creates a copy of the sample in the ‘Location’ path under a new folder using the ‘Name’ specified in the New Project Dialog. We store a master copy of the samples downloaded because we wanted to make sure developers could go back to the original version of a sample without having to remember where they found it on the web. We also wanted to give developers a place to find samples they downloaded when they aren’t connected to the web.
Visual Studio also supports the new sample packs available on the MSDN Code Samples Gallery. Sample packs like the Windows 8 Consumer Preview Sample Pack as well as individual samples can be downloaded through the ‘Online’ tab of the Extension Manager. The samples or sample packs downloaded from the Extension Manager will appear as installed samples the next time you open the New Project Dialog.
When the Visual Studio and MSDN teams were designing the integration of the MSDN Code Samples Gallery with Visual Studio 2012 we discussed various formats for bundling the samples as they were downloaded through the Gallery web services. ZIP and other packaging technologies were considered. We settled on using VSIX because it gave us the ability to introduce two new features for Samples; updates and SDK dependencies.
In Visual Studio 2012 developers will get an update notification whenever a change to the source code for an installed sample is published on the MSDN Code Samples Gallery. Whether the author wants to fix a bug in the sample or introduce a new feature, updates allow authors to make sure all users of that sample can keep up with the latest version if they are interested. If a sample is no longer useful the master copy can be removed from Tools > Extension Manager under the Installed Samples.
Sometimes, samples require the developer to install an SDK with needed reference libraries, headers, or project systems before the sample loads and compiles in Visual Studio. Using VSIX as the underlying technology allowed us to create dependencies between a sample and it’s specific SDK. When you find a sample on the MSDN Code Samples Gallery that was marked with an SDK dependency, Visual Studio 2012 will prompt you to install the SDK before installing the sample making sure you get runnable code.
Samples are just one of the many online assets you can access directly from Visual Studio 2012. We are interested to hear your experience with using Samples through Visual Studio, so send us your feedback! We hope that these connected experiences will help you find the solutions you are looking for quickly while building applications with Visual Studio.
Anthony Cangialosi – Lead Program Manager, Visual Studio
Short Bio: Anthony Cangialosi is lead program manager for the Visual Studio Extensibility team which works on the core extensibility features in Visual Studio as well our connected experiences. Anthony joined the Visual Studio team in 2001 and has worked on a variety of areas including Mobile device development the Visual Studio SDK, and the Visual Studio Ecosystem.
Steven Wilssens – Program Manager, MSDN
Short Bio: Steven Wilssens is the program manager for the MSDN and TechNet gallery and blog platforms. The gallery platform hosts MSDN Code Samples Gallery, Visual Studio Gallery, TechNet Gallery, and TechNet ScriptCenter Gallery. Steven joined Microsoft in 2006 and has been focused on the community experiences inside MSDN and TechNet.
This sounds fantastic. It's always been a little crazy keeping up with the samples that I've put in various places on my machine. Thanks very much, this should be a great help.
With the link you posted directly into the sample source code, there's some page formatting ugliness. The "Official Windows SDK Sample" text box overlaps the text "Solution Explorer" and the scrollbar. It's broken that way in IE9 and Firefox 13, but seems to work fine in Chrome 19. The text in the sample description is also nasty-looking in IE & Firefox, and nicer in Chrome.
I think there's some work that needs to be done on the sample browser interface. The "technologies" list is incomplete; you can see it doesn't contain DirectX for instance, but if you search for it you'll see there is a technology after all. Couldn't you show the complete list there? You could have a collapsed list by default and expand it after a click, if you're worried about space or something.
The contributors list is also confusing - there are separate entries for "Microsoft" and "Windows SDK team" for instance. What does "Microsoft" mean here? Looking at DirectX samples, there are 56 from "Microsoft", 54 from "Windows SDK team", and 3 from "Community". How does it add up?
"Categories" is also messy. There are separate categories for "Audio and video", "Graphics", "2d graphics", "audio", etc. (all with different capitalisations of course...) Are sample authors are allowed to tag things in whatever free-text categories they want? It makes it harder to find things because you have to second-guess which variant of a category the contributor might have used. The same thing seems to affect "technologies" - we see "DirectX", "DirectX SDK", etc. It's disorganised. This is why I prefer closed collections of samples with high-quality interfaces to the modern fad for community content and tags, bah...
Can we please have a separate "platform" for "Metro"?
Ticking and unticking the filter boxes isn't very slick either. It refreshes the whole page after each tick, but the user might have gone through quickly and ticked/unticked in one go. When the page refreshes only one click has been recorded. Can't the web do that sort of thing much better now?
Thanks for sharing.
That's great, samples (especially the more obscure ones) were always way too complicated to find. Hopefully this will make it heaps easier to get started in new tech
I NEED SOME SAMPLE CODE TO CONVERT UPPER CASE MENUS TO PROPER CASE.
I want more CAPS! I need MORE CAPS! Will these give MORE CAPS!? You want to give me MORE CAPS!, I know you do. Give me MORE CAPS! It is very important. Let's talk about MORE CAPS!
@CHRYS look at visualstudiogallery.msdn.microsoft.com/1cd0c3ae-ea51-424e-9fb7-c5768ba1c377
@CHRYS look at visualstudiogallery.msdn.microsoft.com/1cd0c3ae-ea51-424e-9fb7-c5768ba1c37
I'm sorry but, I will uninstall 2012 RC and reinstall 11 Beta.
Wait, why is the "Samples" menu item et al on MSDN in Pascal-case instead of all-caps, like Azure (and Zune!)?
>most likely found it from a Bing search
Um... no, not "most likely", at all. Not even close. I'm... flabbergasted. We're all adults here, YOU DON'T NEED TO LIE TO US! Just for a moment, give the marketing BS a rest. Sigh.</rant>
But back to reality. This is good news. Samples are crucial to learning how things work.
> "No, not "most likely", at all. Not even close"
I don't really agree, and think bing has become a pretty good search engine these days, at least for my purposes. Whenever I'm looking for sample code I can usually find something I need. A search for things like "windows phone sample code", "wcf sample code" or "visual studio sample code" returns useful results. It may not always be on the first page of results, but is usually within the first 2 or three pages. Using bing 'should' help to improve the results over time and so the more it's used the better it 'should' become.
Certainly a good resource but a lot of sample requests go unanswered because the poster hasn't formulated the description of what's needed sufficiently clearly. It would be very helpful to have a way to request clarification to make the project feasible.
Nice idea but seriously we thought VS2011 was badly designed - 2012 makes VS2011 look like perfection in design!
You need to stop adding features and spend serious time looking at the user interface - do you really expect developers to work with this?