A World of Samples at your Fingertips
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.
Where have samples been hiding all this time?
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.
One Samples Gallery
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.
Easy Access to Samples from the Visual Studio IDE
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.
Sample updates and dependencies
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.