Introducing the Visual Studio Pattern Automation Toolkit (VSPAT)                              John Slaby                  ...
    The frameworks and libraries your application depends on are constantly changing, and keeping up with          those ...
Discriminating Services                                  Essential Services                              Commodity Service...
In creating a toolkit for building Visual Studio extensions, we knew that a key to its success was the eliminationof much ...
implementation. For example, variable names could be auto-generated by simply enforcing a common namingconvention, or we c...
Note that because we have decided on a specific implementation for our site, we do not need to provide much ofthe variable...
Figure 4: Text Template Control Logic with Strongly Typed Model Elements                      Figure 5: Text Template Rend...
Once we have a template which creates an element in our pattern implementation, we need to associate thetemplate with the ...
Figure 7: Adding a Context Menu Launch Point     There are many other types of automation in VSPAT that make building a cu...
When you have completed an iteration of your toolkit, including the pattern model, automation, and guidance, it isimportan...
Upcoming SlideShare
Loading in …5
×

Introducing the Visual Studio Pattern Automation Toolkit (VSPAT)

877 views

Published on

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.

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
877
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
4
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Introducing the Visual Studio Pattern Automation Toolkit (VSPAT)

  1. 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. IntroductionThere is much repetition in software development. A content management website, for example, can have many pagesthat allow users to search, view, add, modify, and update database records. These pages have many things in commonand 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 ofbuttons and their function are all common. On the other hand, each database record has different number, type andnames of fields. Dropdown lists have different values. Some lists can be sorted, others not. We will have some recordswith 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 thesepatterns for consistent implementation throughout our application. However, it is difficult to ensure consistency in asystem of any meaningful complexity. Individual differences in coding style, training, and experience can lead todifferent interpretations of a pattern. Additionally, developers do not always understand the overall goals of thearchitecture, 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 thisproblem. The Visual Studio Pattern Automation Toolkit (VSPAT) [MSFT12] is an open source extension to VisualStudio 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, codegenerators 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. 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 thedesign simple and enabled us to provide extensive validation and automation for all of the typical activities associatedwith building Visual Studio extensions that support code generation. As a result, we have produced a tool that cancreate fully functional domain-specific pattern toolkits in as little as half a day. VSPAT enables domain experts tocapture 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 ToolkitsWhy would an organization be motivated to create a pattern toolkit? Imagine the software domain experts of acompany – 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 lessonslearned while creating and deploying these solutions along with intimate knowledge of the architectural decisions andtrade-offs that have been made as products have evolved over time. From an organizational perspective, domainexperts need to communicate their knowledge and experience to the members of the organization who are maintainingand extending this code base, so they can remain focused on directing the strategic growth and evolution of theplatform. No matter how the organization chooses to distribute these artifacts, the developers have always been at adisadvantage. 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 thatapply patterns in the correct way with minimal domain knowledge – tools that address all of the architecturalconstraints and design guidelines of the application automatically and consistently. This has typically beenimpractical 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 smallshop, the domain expert is often the architect, developer, tester, and product owner bundled into one. Rather thanneeding to communicate intent properly among many individuals, the small shop needs to be able to apply limitedresources in the most effective ways. By capturing patterns in tools and automating the generation of these commonpieces of implementation, the limited resources of the small company can remain focused on discovering anddelivering 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 donein creating the application, as detailed in Figure 1. Copyright © 2012, Raytheon Company. All rights reserved.
  3. 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 supportthe application. Components in this layer typically address the most common and most general capabilities of thesystem. Development is largely a process of assembling and configuring the components in standard ways to supportthe application. The Essential Services Layer refers to the features that must be developed for the overall operation of theapplication but are neither novel nor flashy. These features include maintenance and administration, configuration andadaptation, plumbing and other capabilities that provide a complete, fully functional application. Development heretypically 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 competingproducts. Features in this layer add the greatest value to the application. This is where the real creativity andinnovation 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 thesuccess of the application– it will not be fully functional without it - but as a whole it is mostly uninspiring andrepetitious. Tools are much better at doing this kind of work than people are, so we view the Essential Services layeras a natural focus of our automation efforts using VSPAT.4. The Visual Studio EcosystemWorking with Visual Studio provides us with a comprehensive Integrated Development Environment (IDE) thatenables us to deliver the kind of high-quality user experience that developers have come to expect. To help developersintegrate 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 thatmany of the most useful APIs have been around for a very long time. This means they are largely undocumented (theywere originally intended for internal use only) and they are largely unmanaged (wrapped in COM interfaces to legacyC and C++ code). Because they are undocumented, they are difficult to discover and use properly. Because they areunmanaged, they are difficult to debug. Failures of a method call return cryptic result codes which developers may ormay 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 whenlooking to simplify the problem of creating Visual Studio extensions. While you can quickly create graphicaldesigners for any domain, except for simple code generation the tools require extensive knowledge and hard-earnedexperience 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 frommultiple instances of a DSL. These are all difficult and time-consuming tasks using the DSL Tools. Copyright © 2012, Raytheon Company. All rights reserved.
  4. 4. In creating a toolkit for building Visual Studio extensions, we knew that a key to its success was the eliminationof much of this complexity. We wanted to simplify access to a large number of the common Visual Studioextensibility services so that toolkit developers could concentrate on capabilities rather than arcane interfaces. Wewanted to do one thing and one thing well – capture the variable data of patterns in a model which could then be usedto generate code, configurations, and other solution artifacts to eliminate errors and speed solution development.5. A Sample ProblemTo illustrate the use and value of VSPAT, we will provide an example of how we developed a community websiteusing VSPAT. We will discuss the problems we were addressing and the process we followed to create the toolkit.5.1. BackgroundAs part of the community service efforts in our local town, there was a non-profit organization created to help raisefunds to construct an artificial turf field for our sports teams. They needed a website to support the efforts andfacilitate communications with the community. The site needed many of the typical features of a content managementsystem (CMS) - a calendar, announcements, donation support, a gallery for photos and other media, general contentlike contacts, FAQs, and the mission statement, and all of the other information and services that you would expectfrom 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 CommodityServices). We focused on home page usability and a unique way of representing fund-raising progress as ourDiscriminating Services. Much of the rest of the site would be associated with the management of the content, ourEssential Services. Creating a compelling home page and unique progress display was both interesting and fun. But then there wasthe 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 inapproximately two weeks. The content management was another problem altogether. This is where we identified theneed for VSPAT. But before we could create the tool to automate our content management MVC implementation, weneeded 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 ImplementationWe began by taking several of the content types (models in MVC terms) that contained representative properties andconstructed, by hand, the solution we wanted. The ASP.NET MVC tools in Visual Studio already provided supportfor basic code generation, but the results were crude and not robust enough for a real implementation. Although thelook-and-feel could be corrected with style sheets and some hand-tweaking, the code which implemented the viewsand controller was rudimentary. Our application required exception handling, the use of fully-featured open-source controls for some parts of thecontent, custom logging, and better testability across the board. While these modifications could be made to the codewhich was generated by the built-in tools, there was a lot of repetitive modification for every type of content. Inaddition, since we were accepting donations on the site, we needed an industrial-strength implementation that ensuredour site was secure. We took our time during this phase to ensure we had a strong, pattern-oriented referenceimplementation for those initial content types. After several iterations, we were happy with the results and were readyto start designing our toolkit.5.3. Step 2: Refactoring and Identifying VariabilityAn analysis must be performed on the reference implementation at this point to uncover the solution’s essentialvariability. In any application of significant size, there will be elements of the solution which provide similarfunctionality that may be implemented differently. Part of the skill of variability analysis is in refactoring to maximizecommonality and to minimize the variable data that has to be supplied. Often times there are differences that areaccidental, 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. 5. implementation. For example, variable names could be auto-generated by simply enforcing a common namingconvention, or we could generalize a method by using generics rather than explicitly typed values. This separation ofthe essential from accidental variability simplifies both the pattern toolkit development and the toolkit use.5.4. Step 3: Creating the Pattern ModelA pattern toolkit has three key components – the pattern model, automation, and guidance. The pattern model definesa structure for capturing the variability associated with pattern implementation. Automation is comprised ofvalidation, commands, and launch points. Validation ensures the data that is supplied in the pattern model is correctand complete, so that code generation will work properly. Commands implement the code generators and otherautomation 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 forusing the toolkit. We start by creating a pattern model. The elements that comprise a pattern model are relatively simple. There areCollections, 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 inProperties added to a model element and are defined by a name and data type. Extension Points allow the patternmodel developer to define an element that is configured by another pattern toolkit. In this way, pattern toolkits can becomposed 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 modelthat contains a collection of Models, with those elements containing a collection of Properties. Figure 2 illustrates thepattern model created following our variability analysis. Display Order, Display Type and Control Type wereidentified 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. 6. Note that because we have decided on a specific implementation for our site, we do not need to provide much ofthe variable data typically associated with implementing the MVC pattern. This information can be supplied as eitherfixed data in the code generator or can be derived from some other variable data in our pattern model. Thisdemonstrates one of the great powers of abstraction and code generation – the generators can derive much of thevariability without need for the developer to specify those values. For example, the look and feel of web controls canvary 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 itcan be derived from the control type. As another example, appropriate validation attributes can be automatically addedto the Model class based on property types to ensure the ASP.Net MVC validation framework is used properly. Thiscan be exploited to do significant automation where the complete implementation of the Controller to support theCRUD operations along with all of the associated Views can be fully generated from a very small amount of data inour pattern model.5.5. Step 4: Adding Automation using Commands and Launch PointsThe 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 togenerate text files based on data substitution in text blocks using custom control logic. In VSPAT we substitutevariable 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 datain our pattern model. This includes generation of the controller, the model, the standard CRUD views, the unit teststubs and the mock database. We used partial classes to allow any of the generated classes to be safely extended withcustom 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 datafrom our pattern model, which provides strongly-typed access to model elements and properties. The control logic ismodified to perform such tasks as iterating through the model, perform conditional process based on model data, andany other type of processing available using C#. The rendering logic comprises methods that emit the text withvariable data substitution. The result is solution artifacts including code and configuration files. Copyright © 2012, Raytheon Company. All rights reserved.
  7. 7. Figure 4: Text Template Control Logic with Strongly Typed Model Elements Figure 5: Text Template Rendering Logic with Variable SubstitutionCopyright © 2012, Raytheon Company. All rights reserved.
  8. 8. Once we have a template which creates an element in our pattern implementation, we need to associate thetemplate with the appropriate code generation command. There are many predefined commands in VSPAT thatprovide access to all of the standard automation needs of a toolkit builder. Commands are configured through simpleproperties. 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 aselected Model element. To do this, we created and configured a Command to run the T4 processor from the patternmodel 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 byadding a Launch Point to our pattern model. Launch points include menu items, wizards, and events such as OnProperty Changed, On Build or On Drop (for drag-and-drop support). In our MVC Web Administration toolkit, wedecided to use a Menu Item, adding a VSPAT Context Menu Launch Point to the’ Model’ pattern element andconfiguring its properties to invoke our code generation command. Figure 7 shows this process. Copyright © 2012, Raytheon Company. All rights reserved.
  9. 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 andeasy. There are pre-defined commands to unfold entire projects or individual files, update properties in project filesand perform complex data type conversion for specialized transformations. As a result of this, most typical VisualStudio integration work requires little more than selecting the appropriate command and configuring a small set ofproperties. If there is a need for specialized automation not directly supported by VSPAT, the developer can createcustom commands, validators, type converters, value providers, etc.5.6. Step 5: Documenting the ProcessA key component of toolkit development is to document the process of how to use you toolkit. VSPAT provides thetoolkit developer with the ability to provide contextualized guidance. This guidance is intended to impart expertdomain knowledge with recommended practices and processes on how to be productive for the specific solution beingbuilt. Guidance is created by the developer as a Word document and is automatically integrated into the toolkit as partof the toolkit build process. Figure 8 shows how the guidance is presented to the toolkit user. Figure 8: Sample Toolkit Guidance5.7. Step 6: Refining our Toolkit - Review, Refactor and Repeat Copyright © 2012, Raytheon Company. All rights reserved.
  10. 10. When you have completed an iteration of your toolkit, including the pattern model, automation, and guidance, it isimportant to test the product as a user of the toolkit. In this step, you go through the process of unfolding a toolkit inthe same way the end user would; creating and configuring model elements, following guidance topics, invokingautomation, validation, and generating solution artifacts from the model. Figure 9 and Figure 10 demonstrate a testmodel 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 thegenerated output of the toolkit is correct. This process may also help identify areas where the pattern model can beimproved, 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 theVisual 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 VisualStudio environment. Once end users install the pattern toolkit and begin creating their own solutions, additionalimprovements that can be made to the toolkit will be identified; these can be made to the toolkit in an iterative mannerand the new toolkit can be repackaged and redeployed to users.6. Other Toolkit CapabilitiesThere are many other capabilities in VSPAT to support more advanced tooling requirements, including support forcustom type converters, type editors, value providers, validators, and commands. Using Extension Points, you canbuild composable toolkits that allow reuse of pattern toolkits in different types of applications. Wizards allow you toguide the user through a set of steps to gather information, especially useful when the required data depends onprevious 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.

×