A Deep Dive Into The Guidance Automation Toolkit

1. A Deep Dive Into TheGuidance Automation Toolkit Jelle Druyts Compuware .NET Consultant http://jelle.druyts.net

2. Have you ever needed... • A 40-page document full of guidelines • Architectural layers, solution/project structure • Namespaces, class names, method names, ... • Best practices, step-by-step instructions • Visual Studio customizations • Custom actions, menu items, toolbar buttons, ... • Custom “Add New” items (classes, projects, solutions) • Advanced automation • Wizards • Code generation • Quick-start solutions for development teams • Custom Software Factory development • More time to write interesting code?

3. Goals • You will learn • What GAT is, what it can and cannot do • Best practices for GAT development • How GAT fits into the Software Factories vision • You will be able to • Recognize opportunities for GAT • Implement solutions with GAT • Sit back while it does your work

4. Agenda • Visual Studio Extensibility • Guidance Automation Toolkit • GAT Best Practices • GAT & Software Factories

5. A look at the available extensibility features in Visual Studio Visual Studio Extensibility

6. Visual Studio Templates • Project & Item templates • Reusable and customizable project and item stubs • “New Project” and “Add New Item” dialog boxes • Accelerate the development process • Easy deployment: just a .zip file • Content files: source code files, embedded resources, project files, ... • Metadata stored in a “.vstemplate” file (XML) • Copy to a predefined folder (local or on the network) • Capabilities are limited (templates are “dumb”)

7. Visual Studio SDK • Visual Studio has an object model • Call the Visual Studio API’s directly • Use EnvDTE.dll and EnvDTE80.dll • Powerful • Entire Visual Studio object model is exposed • Difficult • Registering custom packages in Visual Studio • COM interop with EnvDTE object model

8. Guidance Automation Toolkit • Guidance Automation • Make reusable code and pattern assets available in Visual Studio • Integrate reusable code into applications • Guide developers through complex procedures • Built upon Visual Studio SDK • Roadmap • Latest release: February 2007 CTP • Will be included in a future release of the Visual Studio • Built and used by Microsoft patterns & practices • Used extensively in their various “Software Factories” • Free download (source code not available)

9. A deep dive into the various elements of GAT Guidance Automation Toolkit

10. GAT & GAX

11. Guidance Life Cycle

12. Guidance Automation Packages • A Guidance Package is • Authored for a specific purpose • A unit of deployment and versioning • A Guidance Package consists of • Visual Studio Templates • Guidance Automation Recipes • The “Guidance Package” meta package • A quick-start solution for Guidance Packages • Generates project structure & sample code • Generates setup project to build MSI

13. A First Look At The Enterprise Library Guidance Package

14. Visual Studio Templates • Provide integration with Visual Studio • “Create New Project/Item” dialog box • Defined in .vstemplate files (XML) • Expanded by the Visual Studio template engine • Associate Visual Studio Templates with recipes

15. Visual Studio Templates <VSTemplate Version="2.0" Type="ProjectGroup" xmlns="http://schemas.microsoft.com/developer/vstemplate/2005"> <TemplateData> <Name>Application Block</Name> <Description>Guidance Package that creates a new Application Block.</Description> <ProjectType>CSharp</ProjectType> <Icon>ApplicationBlock.ico</Icon> </TemplateData> <TemplateContent> <ProjectCollection> <ProjectTemplateLink ProjectName="$ApplicationBlockNamespace$.$ApplicationBlockName$"> Projects\Runtime\Runtime.vstemplate</ProjectTemplateLink> </ProjectCollection> </TemplateContent> <WizardExtension> <Assembly>Microsoft.Practices.RecipeFramework.VisualStudio, Version=1.0.51206.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a</Assembly> <FullClassName>Microsoft.Practices.RecipeFramework.VisualStudio.Templates.UnfoldTemplate </FullClassName> </WizardExtension> <WizardData> <Template xmlns="http://schemas.microsoft.com/pag/gax-template" SchemaVersion="1.0" Recipe="CreateApplicationBlock"> </Template> </WizardData> </VSTemplate>

16. Visual Studio Templates

17. Guidance Automation Recipes • A recipe is a fancy word for a wizard • Automated activity as a series of instructions • Abstracts something a developer would need to do manually • E.g. create projects, add references, ... • Ensures that repetitive (error-prone) activities are performed in a consistent manner • Simplifies complex or repetitive development tasks • Defined in an XML file in the root of the project • Referenced by a Visual Studio Template • Recipe gets run when template is “unfolded”

18. Guidance Automation Recipes <GuidancePackage xmlns="http://schemas.microsoft.com/pag/gax-core" Name="JelleDruyts.EnterpriseLibraryGuidance" Caption="Enterprise Library Guidance" Description="Provides guidance around the creation of Application Blocks" Guid="2cac5b9c-a04f-4a49-8a56-3ee5d63bd83f" SchemaVersion="1.0"> <Recipes> <Recipe Name="CreateApplicationBlock"> <Caption>Create a new Enterprise Library Application Block</Caption> <Arguments> <Argument Name="ApplicationBlockName" Required="true"> <ConverterType="Microsoft.Practices.RecipeFramework.Library.Converters. CodeIdentifierStringConverter, Microsoft.Practices.RecipeFramework.Library" /> </Argument> <Argument Name="ApplicationBlockNamespace" Required="true"> <Converter Type="Microsoft.Practices.RecipeFramework.Library.Converters. NamespaceStringConverter,Microsoft.Practices.RecipeFramework.Library" /> </Argument> </Arguments> <GatheringServiceData> <Wizard xmlns="http://schemas.microsoft.com/pag/gax-wizards" SchemaVersion="1.0"> <Pages> <Page> <Title>Application Block Information</Title> <Fields> <Field ValueName="ApplicationBlockName" Label="Application Block Name" InvalidValueMessage="Must be a valid .NET identifier." /> <Field ValueName="ApplicationBlockNamespace" Label="Namespace" InvalidValueMessage="Must be a valid .NET namespace identifier." /> </Fields> </Page> </Pages> </Wizard> </GatheringServiceData> </Recipe> </Recipes> </GuidancePackage>

19. Wizards • Value gathering strategies • Gather values for recipe arguments • Walk the developer through one or more steps • Any recipe can have a wizard associated with it

20. Value Providers • Provide values for recipe arguments • Optionally dependant of other recipe arguments • Define project names, post-build commands, ... • Retrieve currently selected project, file, ... • Special guest: ExpressionEvaluatorValueProvider • Regular .NET classes (pre-built & custom) <Argument Name="RuntimeProjectName"> <ValueProvider Type="Evaluator" Expression="$(ApplicationBlockNamespace).$(ApplicationBlockName)"> <MonitorArgument Name="ApplicationBlockNamespace" /> <MonitorArgument Name="ApplicationBlockName" /> </ValueProvider> </Argument>

21. Type Converters • Validate the value of a field • CodeIdentifierStringConverter • NamespaceStringConverter • ... • Convert UI fields to a type representation • Regular .NET classes (pre-built & custom) <Argument Name="ApplicationBlockName" Required="true"> <ConverterType="Microsoft.Practices.RecipeFramework.Library.Converters. CodeIdentifierStringConverter, Microsoft.Practices.RecipeFramework.Library" /> </Argument>

22. Actions • Atomic units of work called in a defined sequence by recipes • E.g. add project references, generate classes, add project items, ... • Strongly-typed input and output arguments • Come from the recipe or from another action (chaining) • Typically use EnvDTE • Regular .NET classes (pre-built & custom) <Actions> <Action Name="GetRuntimeProject" Type="...RecipeFramework.Library.Actions.GetProjectAction"> <Input Name="ProjectName" RecipeArgument="RuntimeProjectName" /> <Output Name="Project" /> </Action> <Action Name="GetDesignTimeProject" Type="...RecipeFramework.Library.Actions.GetProjectAction"> <Input Name="ProjectName" RecipeArgument="DesignTimeProjectName" /> <Output Name="Project" /> </Action> <Action Name="AddProjectReference" Type="...Library.Solution.Actions.AddProjectReferenceAction"> <Input Name="ReferringProject" ActionOutput="GetDesignTimeProject.Project" /> <Input Name="ReferencedProject" ActionOutput="GetRuntimeProject.Project" /> </Action> </Actions>

23. Looking Into The Enterprise Library Guidance Package

24. Code Generation • T4 templates (Text Templates Transformation Toolkit) • Combination of text and scriptlets (C#/VB.NET expressions) • E.g. generate data access component from database, ... • ASP.NET-like syntax with full capabilities of .NET <#@ template language="C#" #> <#@ assembly name="System.dll" #> <#@ property processor="PropertyProcessor" name="TargetNamespace" #> <#@ property processor="PropertyProcessor" name="NodeName" #> using System; using Microsoft.Practices.EnterpriseLibrary.Common.Configuration; using Microsoft.Practices.EnterpriseLibrary.Configuration.Design; namespace <#= this.TargetNamespace #> { internal sealed class <#= this.NodeName #>: ConfigurationNode { } }

25. Continuous Guidance • Recipes stay “alive” • Recipes associated with project items • E.g. right-click data access project, choose “Add Data Access Component” • Adding more templates • New projects, e.g. data access project • New project items, e.g. data access component • Uses same mechanisms (wizards, actions, ...)

26. Guidance Navigator • Separate window listing • Overview information • All the available recipes • History of executed recipes • Links to online help, documentation, ...

27. Other GAT Artifacts • Custom Wizard Pages • Add custom user controls to the wizard • Type Editors • Edit values in a wizard through a custom UI • Snippets • Visual Studio snippets that are automatically deployed

28. A look at some development best practices around GAT GAT Best Practices

29. When (Not) To Use GAT • Use GAT when • You have a specific problem with a specific solution that • Is automatable • Must be executed multiple times • Has a development time or risk that is too high to do manually • You can’t use “dumb” Visual Studio Templates • You want to prepare for building a Software Factory • Do not use GAT when • You will use the Guidance Package only once – ever • You can’t/don’t want to invest time in the learning curve • You just think it’s cool

30. Authoring Guidance Packages • There is a learning curve • Do not involve everyone • Make 1 person/team responsible for GAT • Once the knowledge is there, investment pays off quickly • Don’t try to build everything at once • Start automating simple scenarios • Incrementally increase complexity • Add templates, logic and guidance along the way

31. GAT & Source Control • Guidance Package “state” is kept in a .gpState file (XML) with the solution file (.sln) • Indicates which Guidance Packages are associated with the solution • Contains recipe references and some state • Can/should be checked in to Source Control

32. Guidance Package State • Guidance Packages are “stateless” • Recipe arguments (wizard fields) aren’t available after the wizard finished • Store values out-of-band (e.g. to disk, database, ...) • Lookup values dynamically in solution if possible (through Visual Studio SDK, e.g. default namespace) • The generated code is the “model” • DSLs can fill this gap

33. A look at the big picture GAT & Software Factories

34. Software Factories • Initiative developed by Microsoft patterns & practices Web Service SF - Web Client SF Smart Client SF - Mobile Client SF • Current state: infancy • Written documentation + Guidance Packages + Reference Implementations • GAT mostly used for wizards & code generation • The code is the “model” • The road ahead: towards the Grand Vision • Domain Specific Languages (DSLs) capture and persist the model • Programming code becomes a “rendering” of the model • GAT guides developers through complex tasks

35. A Possible Future (EFx)

36. GAT & Software Factories • Software Factory enabling technologies: • Visual Studio Extensibility Model • Visual Studio Modeling Tools (Designers) • Domain Specific Language Tools (DSLs) • Small, highly focused languages that model and solve clearly identifiable problems • Guidance Automation Toolkit • Generate initial solution structure • Wizards & code generation • Can be used to provide guidance and context to DSLs • Launch recipes from shapes in the DSLs • Enable DSLs in certain parts of the solution

37. Wrapping up... In Closing

38. Key Points • GAT is the next step in Visual Studio automation • Builds on Visual Studio Templates & Visual Studio SDK • GAT can help you • Automate repetitive tasks and complex processes • Provide guidance right inside the Visual Studio solution • Generate code with the powerful T4 engine • Provide context and guidance continuously • Make sure guidelines and best practices are enforced • Be lazy  • GAT is a key part of Software Factories • Understand the present • Prepare for the future

39. Resources • Guidance Automation Toolkit • Home - http://msdn.microsoft.com/vstudio/teamsystem/workshop/gat/ • Forum - http://forums.microsoft.com/msdn/showforum.aspx?forumid=78&siteid=1 • Community site - http://www.guidanceautomation.net/cs/default.aspx • My Guidance Automation series - http://jelle.druyts.net/CategoryView.aspx?category=Blog|Programming|.NET|GuidanceAutomation • Software Factories • Home - http://msdn2.microsoft.com/en-us/teamsystem/aa718951.aspx • Guidance Automation Toolkit and Domain-Specific Language Tools for Visual Studio 2005: Integration Scenarios -http://msdn2.microsoft.com/en-us/library/aa905334.aspx • EFx - http://msdn2.microsoft.com/en-us/library/aa905331.aspx • Clarius Software Factories Toolkit - http://softwarefactoriestoolkit.net/ • Microsoft • Microsoft patterns & practices: http://msdn.microsoft.com/practices/ • Enterprise Library 2.0: http://msdn.microsoft.com/library/en-us/dnpag2/html/EntLib2.asp

40. Thank You! • Thanks for your attention • I'll be happy to answer all your questions • Right after the session • Compuware Booth • Community Booth: Ask-The-Experts • VISUG Booth