1. Introducing the Visual Studio Pattern Automation Toolkit (VSPAT)
John Slaby Ian Goodsell
Raytheon Company Raytheon Company
Waltham, MA, USA Waltham, MA, USA
john_m_slaby@raytheon.com ian_goodsell@raytheon.com
Abstract
A large part of the work in developing any application of significant value is repetitious, uninteresting
and time-consuming. This provides excellent opportunities for automation through custom tooling to
eliminate error-prone and repetitious work. There are many challenges, however, in creating the tools
to do the automation. Either they are quick and dirty, and therefore limited in capability, hard to
maintain, and hard to use; or they are full-featured and expensive to develop and maintain. The Visual
Studio Pattern Automation Toolkit (VSPAT), a Visual Studio extension, bridges the gap between these
extremes, creating full-featured toolkits that are quick and easy to build and easy for developers to use.
VSPAT simplifies the process of developing custom tools – it is a toolkit for creating toolkits. This
paper will provide an overview of VSPAT and provide an example of its use, illustrating all of the key
capabilities and features it provides.
1. Introduction
There is much repetition in software development. A content management website, for example, can have many pages
that allow users to search, view, add, modify, and update database records. These pages have many things in common
and many differences. On the one hand, we find that the style of the page, the way we accept different types of input,
the validation performed on input, the responses we return for success and failure of a request, and the types of
buttons and their function are all common. On the other hand, each database record has different number, type and
names of fields. Dropdown lists have different values. Some lists can be sorted, others not. We will have some records
with a parent/child relationship. Much in common, much that is different: this is true of most applications.
Good software practices suggest we identify the common patterns at the core of this repetition and use these
patterns for consistent implementation throughout our application. However, it is difficult to ensure consistency in a
system of any meaningful complexity. Individual differences in coding style, training, and experience can lead to
different interpretations of a pattern. Additionally, developers do not always understand the overall goals of the
architecture, so although the pattern may be well implemented, it may be at odds with the architectural intent.
Working with Raytheon on an applied research project, Microsoft developed a set of tools to address this
problem. The Visual Studio Pattern Automation Toolkit (VSPAT) [MSFT12] is an open source extension to Visual
Studio 2010 that helps developers automate pattern application. Starting with a sample implementation of a pattern,
you can use VSPAT to create a ‘pattern toolkit’ comprised of a model that captures the pattern variability, code
generators that produce instances of the pattern from the model, and guidance for using the toolkit.
There are many advantages to using pattern toolkits when developing an application:
 Time to implement the application is dramatically reduced because applying instances of the pattern requires
only specification of the variable data.
 The consistency provided by a pattern toolkit means that your application has fewer bugs. The variable data
entered into the model can be validated to ensure it is correct and consistent and will result in a valid
implementation. If a bug is found in the code generator for the pattern, it can be fixed once in the template
and the bug will be fixed throughout your application.
Copyright © 2012, Raytheon Company. All rights reserved.

2.  The frameworks and libraries your application depends on are constantly changing, and keeping up with
those changes can be a significant maintenance effort. With a pattern toolkit, you can update the code
generators to accommodate those changes, and in one step update the entire application.
 You don’t have to live with someone else’s idea of how a pattern should be implemented. The code
generators produce your implementations based on your patterns to meet the specific needs of your
application.
 Once you have captured the variable data in the pattern model, the underlying implementation can be
changed in any way you want. This can include improvements to your design as requirements change, or a
major architectural refactoring to take advantage of new technologies.
In creating VSPAT, we focused on the domain of software pattern implementation. This enabled us to keep the
design simple and enabled us to provide extensive validation and automation for all of the typical activities associated
with building Visual Studio extensions that support code generation. As a result, we have produced a tool that can
create fully functional domain-specific pattern toolkits in as little as half a day. VSPAT enables domain experts to
capture implementation patterns in a light-weight framework which simplifies automation, guidance, code generation,
and packaging. It is a Toolkit for Toolkit Developers.
2. Motivation for Creating Pattern Toolkits
Why would an organization be motivated to create a pattern toolkit? Imagine the software domain experts of a
company – the senior engineers and architects who are responsible for directing the evolution of software products.
Due to the nature of their jobs and responsibilities, these experts have experience in the best practices and lessons
learned while creating and deploying these solutions along with intimate knowledge of the architectural decisions and
trade-offs that have been made as products have evolved over time. From an organizational perspective, domain
experts need to communicate their knowledge and experience to the members of the organization who are maintaining
and extending this code base, so they can remain focused on directing the strategic growth and evolution of the
platform.
No matter how the organization chooses to distribute these artifacts, the developers have always been at a
disadvantage. Some of the many challenges faced by them include:
 Documentation which doesn’t accurately reflect the actual system implementation.
 Documentation that is missing content on the specific problem the user is attempting to solve
 Lack of time in order to effectively understand the problem domain
 Samples that do not integrate correctly into the user’s specific problem
 Unintended effects of sample code used in an unexpected way
Unfortunately, no amount of documentation will ever solve this problem. What is needed are custom tools that
apply patterns in the correct way with minimal domain knowledge – tools that address all of the architectural
constraints and design guidelines of the application automatically and consistently. This has typically been
impractical because of the cost of developing such custom tools and is the motivation for the Pattern Toolkit.
Pattern Toolkits are as relevant for the small, one-man shop as they are for the large organization. In the small
shop, the domain expert is often the architect, developer, tester, and product owner bundled into one. Rather than
needing to communicate intent properly among many individuals, the small shop needs to be able to apply limited
resources in the most effective ways. By capturing patterns in tools and automating the generation of these common
pieces of implementation, the limited resources of the small company can remain focused on discovering and
delivering the innovations that set their product apart from the rest of the competition.
3. Finding the Tooling ‘Sweet Spot’
One rather simple way of looking at an application’s structure is by separating the kinds of development that are done
in creating the application, as detailed in Figure 1.
Copyright © 2012, Raytheon Company. All rights reserved.

3. Discriminating Services
Essential Services
Commodity Services
Figure 1: Layers of an Application
The Commodity Services Layer refers to the foundation of any modern application. This is made up of the off-
the-shelf infrastructure components (such as operating system, middleware, runtime libraries, etc.) chosen to support
the application. Components in this layer typically address the most common and most general capabilities of the
system. Development is largely a process of assembling and configuring the components in standard ways to support
the application.
The Essential Services Layer refers to the features that must be developed for the overall operation of the
application but are neither novel nor flashy. These features include maintenance and administration, configuration and
adaptation, plumbing and other capabilities that provide a complete, fully functional application. Development here
typically has a significant amount of repetition and can take up the majority of the development schedule.
The Discriminating Services Layer encompasses the features that differentiate the application from competing
products. Features in this layer add the greatest value to the application. This is where the real creativity and
innovation comes to play in the development process.
An organization would ideally like to concentrate its time and efforts in developing the discriminators. However,
we often end up spending the majority of our time supporting the essential services. Work in this layer is vital to the
success of the application– it will not be fully functional without it - but as a whole it is mostly uninspiring and
repetitious. Tools are much better at doing this kind of work than people are, so we view the Essential Services layer
as a natural focus of our automation efforts using VSPAT.
4. The Visual Studio Ecosystem
Working with Visual Studio provides us with a comprehensive Integrated Development Environment (IDE) that
enables us to deliver the kind of high-quality user experience that developers have come to expect. To help developers
integrate new capabilities into Visual Studio, there are a rich set of APIs for extending the development environment.
These APIs include services for integrating new tools, adding custom code generators, adding or enhancing editors,
adding new languages, updating project file, adding items to the solution, etc. The challenge for developers is that
many of the most useful APIs have been around for a very long time. This means they are largely undocumented (they
were originally intended for internal use only) and they are largely unmanaged (wrapped in COM interfaces to legacy
C and C++ code). Because they are undocumented, they are difficult to discover and use properly. Because they are
unmanaged, they are difficult to debug. Failures of a method call return cryptic result codes which developers may or
may not be able to translate into meaningful errors that can be quickly corrected.
Even the more recent capabilities in Visual Studio, such as the DSL Tools, have significant shortcomings when
looking to simplify the problem of creating Visual Studio extensions. While you can quickly create graphical
designers for any domain, except for simple code generation the tools require extensive knowledge and hard-earned
experience to do many of the other common activities associated with extending the IDE: adding menu launch points,
unfolding project templates, modifying project files, locating artifacts in the solution, and aggregating the data from
multiple instances of a DSL. These are all difficult and time-consuming tasks using the DSL Tools.
Copyright © 2012, Raytheon Company. All rights reserved.

4. In creating a toolkit for building Visual Studio extensions, we knew that a key to its success was the elimination
of much of this complexity. We wanted to simplify access to a large number of the common Visual Studio
extensibility services so that toolkit developers could concentrate on capabilities rather than arcane interfaces. We
wanted to do one thing and one thing well – capture the variable data of patterns in a model which could then be used
to generate code, configurations, and other solution artifacts to eliminate errors and speed solution development.
5. A Sample Problem
To illustrate the use and value of VSPAT, we will provide an example of how we developed a community website
using VSPAT. We will discuss the problems we were addressing and the process we followed to create the toolkit.
5.1. Background
As part of the community service efforts in our local town, there was a non-profit organization created to help raise
funds to construct an artificial turf field for our sports teams. They needed a website to support the efforts and
facilitate communications with the community. The site needed many of the typical features of a content management
system (CMS) - a calendar, announcements, donation support, a gallery for photos and other media, general content
like contacts, FAQs, and the mission statement, and all of the other information and services that you would expect
from a site focused on a community fund raising effort.
In the context of our three layers discussed above, we chose ASP.NET MVC as our platform (our Commodity
Services). We focused on home page usability and a unique way of representing fund-raising progress as our
Discriminating Services. Much of the rest of the site would be associated with the management of the content, our
Essential Services.
Creating a compelling home page and unique progress display was both interesting and fun. But then there was
the rest of the work… the bulk of which was the content management. This included support to display, add, modify,
delete, find, and list all of the many different types of content on the site. The discriminating work was completed in
approximately two weeks. The content management was another problem altogether. This is where we identified the
need for VSPAT. But before we could create the tool to automate our content management MVC implementation, we
needed a reference implementation to be able to identify and model the patterns we wanted to use on our site.
5.2. Step 1: Creating the Reference Implementation
We began by taking several of the content types (models in MVC terms) that contained representative properties and
constructed, by hand, the solution we wanted. The ASP.NET MVC tools in Visual Studio already provided support
for basic code generation, but the results were crude and not robust enough for a real implementation. Although the
look-and-feel could be corrected with style sheets and some hand-tweaking, the code which implemented the views
and controller was rudimentary.
Our application required exception handling, the use of fully-featured open-source controls for some parts of the
content, custom logging, and better testability across the board. While these modifications could be made to the code
which was generated by the built-in tools, there was a lot of repetitive modification for every type of content. In
addition, since we were accepting donations on the site, we needed an industrial-strength implementation that ensured
our site was secure. We took our time during this phase to ensure we had a strong, pattern-oriented reference
implementation for those initial content types. After several iterations, we were happy with the results and were ready
to start designing our toolkit.
5.3. Step 2: Refactoring and Identifying Variability
An analysis must be performed on the reference implementation at this point to uncover the solution’s essential
variability. In any application of significant size, there will be elements of the solution which provide similar
functionality that may be implemented differently. Part of the skill of variability analysis is in refactoring to maximize
commonality and to minimize the variable data that has to be supplied. Often times there are differences that are
accidental, that is, because of coding style or individual choice but not because of any specific requirement of the
Copyright © 2012, Raytheon Company. All rights reserved.

5. implementation. For example, variable names could be auto-generated by simply enforcing a common naming
convention, or we could generalize a method by using generics rather than explicitly typed values. This separation of
the essential from accidental variability simplifies both the pattern toolkit development and the toolkit use.
5.4. Step 3: Creating the Pattern Model
A pattern toolkit has three key components – the pattern model, automation, and guidance. The pattern model defines
a structure for capturing the variability associated with pattern implementation. Automation is comprised of
validation, commands, and launch points. Validation ensures the data that is supplied in the pattern model is correct
and complete, so that code generation will work properly. Commands implement the code generators and other
automation tasks on behalf of the user. Commands are invoked through launch points which include menu items,
wizards, or events such as On Build or On Save. Integrated guidance helps the user follow the correct process for
using the toolkit.
We start by creating a pattern model. The elements that comprise a pattern model are relatively simple. There are
Collections, Elements, and Extension Points. Collections represent either a hierarchy or a grouping of elements.
Elements represent parts of the pattern that require user-supplied (variable) data. Variable data is captured in
Properties added to a model element and are defined by a name and data type. Extension Points allow the pattern
model developer to define an element that is configured by another pattern toolkit. In this way, pattern toolkits can be
composed of multiple, smaller pattern toolkits, making the toolkits themselves more reusable.
In an ASP.NET MVC application, everything starts with the Model, and so we began by creating a pattern model
that contains a collection of Models, with those elements containing a collection of Properties. Figure 2 illustrates the
pattern model created following our variability analysis. Display Order, Display Type and Control Type were
identified as items which can be configured by the user and so we add properties to capture that data.
Figure 2: MVC Web Administration Pattern Model
Copyright © 2012, Raytheon Company. All rights reserved.

6. Note that because we have decided on a specific implementation for our site, we do not need to provide much of
the variable data typically associated with implementing the MVC pattern. This information can be supplied as either
fixed data in the code generator or can be derived from some other variable data in our pattern model. This
demonstrates one of the great powers of abstraction and code generation – the generators can derive much of the
variability without need for the developer to specify those values. For example, the look and feel of web controls can
vary based on type. Our code generator can automatically specify the appropriate CSS class by evaluating the user-
specific control type. So, although the CSS class is variable, it doesn’t need to show up in our pattern model because it
can be derived from the control type. As another example, appropriate validation attributes can be automatically added
to the Model class based on property types to ensure the ASP.Net MVC validation framework is used properly. This
can be exploited to do significant automation where the complete implementation of the Controller to support the
CRUD operations along with all of the associated Views can be fully generated from a very small amount of data in
our pattern model.
5.5. Step 4: Adding Automation using Commands and Launch Points
The goal of the automation is to perform activities on behalf of the user to ensure the implementation is consistent,
correct, and compatible with the overall system design. VSPAT uses the Visual Studio T4 text templating engine to
generate text files based on data substitution in text blocks using custom control logic. In VSPAT we substitute
variable data from the pattern model and other sources into the generated source files.
For our MVC Web Administration toolkit, we are able to completely generate many MVC artifacts from the data
in our pattern model. This includes generation of the controller, the model, the standard CRUD views, the unit test
stubs and the mock database. We used partial classes to allow any of the generated classes to be safely extended with
custom methods and properties. The process of adding a text template to the toolkit is illustrated in Figure 3.
Figure 3: Adding Text Templates to the Pattern Toolkit
The stub text template which we unfolded through this automation is then modified to access the appropriate data
from our pattern model, which provides strongly-typed access to model elements and properties. The control logic is
modified to perform such tasks as iterating through the model, perform conditional process based on model data, and
any other type of processing available using C#. The rendering logic comprises methods that emit the text with
variable data substitution. The result is solution artifacts including code and configuration files.
Copyright © 2012, Raytheon Company. All rights reserved.

7. Figure 4: Text Template Control Logic with Strongly Typed Model Elements
Figure 5: Text Template Rendering Logic with Variable Substitution
Copyright © 2012, Raytheon Company. All rights reserved.

8. Once we have a template which creates an element in our pattern implementation, we need to associate the
template with the appropriate code generation command. There are many predefined commands in VSPAT that
provide access to all of the standard automation needs of a toolkit builder. Commands are configured through simple
properties.
Figure 6: Adding Automation to a Pattern Model Element
In our MVC Web Administration toolkit, we wanted to give the user the ability to generate MVC support for a
selected Model element. To do this, we created and configured a Command to run the T4 processor from the pattern
model using our text template. An example of how the Command was created and configured is shown in Figure 6.
Having created this command, we then need to provide a mechanism for executing that command. We do this by
adding a Launch Point to our pattern model. Launch points include menu items, wizards, and events such as On
Property Changed, On Build or On Drop (for drag-and-drop support). In our MVC Web Administration toolkit, we
decided to use a Menu Item, adding a VSPAT Context Menu Launch Point to the’ Model’ pattern element and
configuring its properties to invoke our code generation command. Figure 7 shows this process.
Copyright © 2012, Raytheon Company. All rights reserved.

9. Figure 7: Adding a Context Menu Launch Point
There are many other types of automation in VSPAT that make building a custom toolkit incredibly quick and
easy. There are pre-defined commands to unfold entire projects or individual files, update properties in project files
and perform complex data type conversion for specialized transformations. As a result of this, most typical Visual
Studio integration work requires little more than selecting the appropriate command and configuring a small set of
properties. If there is a need for specialized automation not directly supported by VSPAT, the developer can create
custom commands, validators, type converters, value providers, etc.
5.6. Step 5: Documenting the Process
A key component of toolkit development is to document the process of how to use you toolkit. VSPAT provides the
toolkit developer with the ability to provide contextualized guidance. This guidance is intended to impart expert
domain knowledge with recommended practices and processes on how to be productive for the specific solution being
built. Guidance is created by the developer as a Word document and is automatically integrated into the toolkit as part
of the toolkit build process. Figure 8 shows how the guidance is presented to the toolkit user.
Figure 8: Sample Toolkit Guidance
5.7. Step 6: Refining our Toolkit - Review, Refactor and Repeat
Copyright © 2012, Raytheon Company. All rights reserved.

10. When you have completed an iteration of your toolkit, including the pattern model, automation, and guidance, it is
important to test the product as a user of the toolkit. In this step, you go through the process of unfolding a toolkit in
the same way the end user would; creating and configuring model elements, following guidance topics, invoking
automation, validation, and generating solution artifacts from the model. Figure 9 and Figure 10 demonstrate a test
model instance being created and configured using the pattern toolkit as a toolkit user.
Figure 9: User Experience Configuring a Pattern Model Instance
Reviewing the use of the toolkit is a critical step intended to ensure the user experience is seamless and the
generated output of the toolkit is correct. This process may also help identify areas where the pattern model can be
improved, or automation can be added to improve the productivity of the user.
Figure 10: User Experience Using Automation to Invoke Code Generation
Deploying a pattern toolkit to end users is simplified by VSPAT: all pattern toolkits are packaged using the
Visual Studio Extension framework (VSIX). By default, all assets of the toolkit, including the pattern model,
guidance, text templates, and automation are built into a single file that is used to install the toolkit into a user’s Visual
Studio environment. Once end users install the pattern toolkit and begin creating their own solutions, additional
improvements that can be made to the toolkit will be identified; these can be made to the toolkit in an iterative manner
and the new toolkit can be repackaged and redeployed to users.
6. Other Toolkit Capabilities
There are many other capabilities in VSPAT to support more advanced tooling requirements, including support for
custom type converters, type editors, value providers, validators, and commands. Using Extension Points, you can
build composable toolkits that allow reuse of pattern toolkits in different types of applications. Wizards allow you to
guide the user through a set of steps to gather information, especially useful when the required data depends on
previous inputs. See [MSFT12] for full documentation, hands-on labs, and the latest version of the toolkit.
References
[MSFT12] http://vspat.codeplex.com/
Copyright © 2012, Raytheon Company. All rights reserved.