Practical Code Generation in .NET: Covering Visual Studio 2005, 2008, and 2010

Enlist Visual Studio’s Built-in Code Generation Tools to Write Better Software Faster   Automatic code generation can dramatically increase your productivity, improve code quality and maintainability, promote reuse, and help you extend best practices throughout your development organization. .NET and Visual Studio contain many powerful, code-generation tools—and this book shows you how to succeed with all of them. With Practical Code Generation in .NET, spend less time writing monotonous, repetitive code—leaving more time to address troublesome areas!   Microsoft MVP Peter Vogel covers code generation with Visual Studio 2010, 2008, and 2005, as well as all recent versions of .NET, including .NET 4.0. You’ll learn when enlisting code generation makes sense and how to design solutions that build on the skills and resources you already have.   Writing for experienced programmers, Vogel shows how to generate reliable code using procedural code, Visual Studio add-ins, XML, configuration files, and more—including Microsoft’s innovative CodeDOM technology for generating code in multiple languages. He brings everything together in three complete, chapter-length case studies.   Coverage includes Understanding the structure of .NET code-generation solutions and best practices for architecting them Creating Visual Studio add-ins that quickly integrate code generation into day-to-day activities Using objects and methods to add or remove project components Using text insertion to generate code using any tool—even standard string handling functions Working with the specific features of C#, Visual Basic .NET, and ASP.NET Generating more concise code with .NET’s new Text Template Transformation Toolkit (T4) Building code-generation solutions with Visual Studio templates, attributes, and custom tools Distributing code-generation solutions

Table of Contents:
Foreword . . . xiv Preface . . . xvi Acknowledgments . . . xx About the Author . . . xxi Chapter 1 Introducing Code Generation . . . 1 Repetitive Code: Your History . . . 2 Copy-and-Paste . . . 2 General-Purpose Code . . . 3 Benefits of Code Generation . . . 4 When to Use Code Generation . . .7 Best Practices in Code-Generation Solutions . . . 10 Code-Generation Process . . . 11 Code-Generation Tools . . .12 Model-Driven Architecture, Declarative Programming, and Code Generation . . . 14 Model-Driven Architecture . . . 14 Declarative Programming . . . 17 PART I: TOOLS . . . 19 Chapter 2 Integrating with Visual Studio . . . 21 Design-Time Integration . . .22 Starting Your Visual Studio Add-In . . . 23 Laying the Foundation . . . 24 Integrating with Visual Studio . . . 27 Writing a Generation Class in Visual Studio . . . 30 Working with COM . . .31 Debugging Issues in Visual Studio 2005/2008 . . . 32 The OnConnection Method . . .34 Removing Add-In Menus . . . 35 Creating a Menu-Driven User Interface . . . 36 Extending Your Menus . . . 36 Adding Additional Menus . . . 37 Finding the Menu . . . 38 Adding the Menu Item . . . 40 Supporting Multiple Menu Items . . . 42 Creating Submenus . . .43 Adding Submenus . . . 44 Context Menus . . . 44 Accessing the Context . . . 46 Working with Visual Studio Windows . . . 49 Using the Task List Window . . .49 Retrieving Selected Items . . . 50 Writing Messages to the Output Window and the TaskList . . . 51 AutoNavigate in Visual Studio 2005 . . .55 Final Touches . . . 57 Responding to Events . . . 58 Simple Events . . . 58 Filtered Events . . . 60 Working with Document Events . . . 61 Extracting Event Packages . . . 63 Finishing Events . . . 64 Accepting Input . . . 65 Options . . . 65 Creating a Dockable Window . . .  65 Saving Input Values . . .69 Adding an Options Tab . . . 71 Accessing and Saving Option Properties . . . 73 Integrating with Visual Studio . . . 76 Chapter 3 Manipulating Project Components . . . 77 The Code Model . . . 78 Code Model Caveats . . . 79 Managing Projects and Solutions . . . 80 Creating Projects . . . 80 Referencing the Project Items Collection . . . 82 Adding Folders to a Project . . .83 Adding Files . . . 84 Copying Boilerplate Code . . . 86 Generating Code . . . 86 Introducing CodeModel and FileCodeModel . . . 86 Generating Code . . . 89 Modifying and Analyzing Components . . .110 Finding Projects and Project Items . . . 110 Reading Project Properties . . .113 Removing Items . . . 113 Checking for Changes . . . 114 Processing Components in a File . . . 114 Processing All the Components in a File . . . 114 Retrieving Components by Name . . . 116 Retrieving Components by Location . . .117 Working with Retrieved Elements . . . 118 Determining If an Element Can Be Modified . . . 118 Writing Language-Specific Code . . . 119 Using CodeElement with the Position Parameter . . . 119 Choosing Interfaces . . . 120 The CodeEvent Object . . . 121 Working with the CodeType Objects . . . 121 Finding Components with CodeType . . .121 Simple CodeType Options . . .124 Working with Comments and Documentation Comments . . . 124 Working with Related Classes . . . 125 Storing Information . . . 126 Storing Strings in the Globals Object . . . 127 Working with Project Components . . . 128 Chapter 4 Modifying Code in the Editor . . . 129 Opening and Closing Documents and TextDocuments . . . 130 Accessing the Document/TextDocument . . . 130 Making the Document Available to the Developer . . . 131 Closing the Document . . .132 Backing Out Changes . . .133 Creating and Finishing a Context . . . 133 Getting Information on the Context . . . 135 Creating EditPoints to Access Text . . . 135 Retrieving EditPoints with the TextDocument . . . 136 Retrieving EditPoints with the FileCodeModel . . . 136 Retrieving CodeElements from Text . . . 138 Retrieving Information . . .139 Document and TextDocument Objects . . . 139 Document Object Only . . . 140 EditPoint . . .140 Accessing Text with an EditPoint . . . 140 Retrieving Text . . . 141 Relocating the EditPoint . . . 143 Finding Text . . . 144 Finding Text with Regular Expressions . . . 146 Working with Bookmarks . . . 147 Creating Bookmarks . . . 147 Inserting, Replacing, and Formatting Text . . . 149 Inserting and Deleting Text . . .149 Replace Selected Text . . . 150 Bulk Insertions . . . 151 Cleaning Up after Insertions . . .  151 Bulk Replacements . . .152 Controlling the Text Being Displayed . . .153 Formatting Code . . . 154 Smart Formatting . . . 154 Controlled Indenting . . . 154 Inserting and Reading Text . . . 155 Chapter 5 Supporting Project-Specific Features . . . 157 Introducing the VSLangProj Libraries . . . 158 Working with Projects . . . 160 Reference Objects . . .170 Managing a “Projectless” Website . . . 170 Working with the Website . . .171 Adding New Components . . .172 Working with Website Items . . . . 179 Project-Specific Features . . .. . . 180 Chapter 6 Generating Language-Neutral Code . . . 181 A Comprehensive Example . . . 182 The Code to Be Generated . . . 183 Using Variables, Data Types, and Literals . . . 184 Creating Namespaces and Classes . . .185 Adding Methods with Parameters . . . 186 Adding Statements to Methods . . . 187 Generating Code . . . 188 Declarations . . . 189 Local Scalar Variables . . . 190 Arrays . . . 193 Delegates . . . 195 Defining Classes . . . 197 Inheritance and Interfaces . . .198 Generics and Partial Classes . . . 199 Class Members . . . 200 Fields . . . 200 Methods . . . 201 Parameters . . . 205 Events . . . 206 Constructors . . . 211 Entry Points . . . 213 Properties . . . 214 Creating an Indexer . . . 216 Statements and Expressions . . . 216 Expressions . . . 217 Statements . . . 224 Code Structures . . . 228 If...Then . . . 228 For Loops . . . 229 Try...Catch . . . 232 When All Else Fails: Code Snippets . . . 235 Snippet Expressions and Statements . . .236 Compile Units . . . 237 Other Code Features . . . 238 Generating Valid Names . . . 238 Adding Comments . . . 239 Adding Custom Attributes . . . 240 Using Directives to Organize Code into Regions . . . 241 UserData (Option Strict and Option Compare) . . . 242 Code Providers . . . 243 Generating Code . . . 243 Generating Partial Code . . . 246 Compiling Code . . . 246 Generating Code . . . 247 Chapter 7 Generating Code from Templates with T4 . . . 249 T4 in Visual Studio . . . 251 T4 Code-Generation Strategies . . . 252 Options for Extending T4 . . . 253 The T4 Process . . . 253 Creating a T4 Template . . . 254 Escape Characters . . . 257 Directives . . . 258 Adding Helper Methods . . . 261 Generating Errors and Warnings . . . 263 Review . . . 264 Accessing the Generated Code . . .  264 Controlling Code Indentation . . .  264 Extending T4 . . . 265 Creating a New Base Class . . .  265 Defining Custom Directives . . .  267 Invoking Templates from Code . . .  270 Configuring the Project . . . 271 Invoking the Template Using the Visual Studio Host . . . 272 Invoking the Template with a Custom Host . . . 273 Defining a Custom Host . . .274 Adding Custom Methods to the Host . . .280 Passing Parameters to a Template . . . 281 Supporting Custom Directives . . . 282 Leveraging Templates . . .283 Chapter 8 Other Tools: Templates, Attributes, and Custom Tools . . . 285 Item Templates . . . 286 Using the Wizard . . . 287 Template Components . . . 290 Modifying/Creating a Template Control File . . . 293 Attributes . . . 305 Introducing Attributes . . . 306 Creating a Custom Attribute . . . 308 Processing Attributes with Reflection . . . 311 Documenting with Attributes . . . 315 Generating Code from Custom File Formats . . . 315 Setting Up the Project . . . 316 Integrating Custom Tools . . . 323 Reviewing the Tools . . . 329 PART II: CASE STUDIES . . . 331 Chapter 9 Case Study: Generating a Connection String Manager . . . 333 Defining the Problem . . . 334 A Model Solution . . . 335 Supporting Customization . . . 337 Setting Up the Add-In . . . 337 Defining the Add-In . . . 337 Creating the Menu . . . 338 Calling the Solution . . . 342 Creating the Code Generator . . . 343 Finding the Project . . . 344 Does Anything Need to be Done? . . . 345 Segregating Generated Code . . . 346 Adding the Template . . . 349 Customizing the Template . . . 350 Fixing the Namespace . . . 352 Modifying the Class . . . 353 Adding a Reference . . . 355 Generating Code . . . 355 Reading Input . . . 356 Processing the Configuration File . . . 357 Adding Property Code . . . 358 Notifying the Developer . . . 359 Defining the Output Utility . . . 359 Handling the Task List . . . 360 Using the Output Method . . . 361 Supporting Customization . . . 362 Customizable Code . . . 362 Accepting Input . . . 363 Defining the Options Dialog . . . 363 Saving Developer Choices . . . 364 Option Manager Class . . . 365 Creating the User Control . . . 366 Implementing the User Control Interface . . . 367 Integrating with the Add-In . . . 369 Generating Custom Code . . . 370 Adding Custom Code . . . 371 Tying Generation to Events . . . 371 Integrating with Builds . . . 372 Integrating with Documents . . . 373 Generating a Simple Class . . . 375 Chapter 10 Case Study: Generating Validation Code . . . 377 Defining the Problem . . . 378 The Dedicated Code Solution . . . 378 The Generalized Code Solution . . . 380 The Generated Code Solution . . . 380 Creating the Validator . . . 382 The EventArgs Parameter . . . 386 Creating Other Code-Generated Validators . . . 387 Adding the Validator to the Toolbox . . .387 Starting the Code-Generation Project . . . 388 Wiring Up the Add-In . . .389 Creating a Submenu . . . 390 Handling Multiple Documents in Events . . . 392 Starting the Generation Utility . . . 395 Responding to the Add-In . . .395 Defining a Template . . . 397 Generating Code . . . 400 Starting the Process . . . 400 Managing the Code-Generation Process . . . 402 Utility Methods . . . 404 Processing the Validators . . . 407 Inserting Code . . . 410 Specifying Code with the CodeDom . . . 411 Generating the Lookup Methods . . . 412 Generating Code in the Target Language . . . 421 Supporting “Projectless” Websites . . . 421 Adding Code . . . 422 Handling Errors . . . 425 Building a Complete Code-Generation Solution . . . 426 Chapter 11 Case Study: Generating Data-Conversion Code . . . 427 Defining the Problem . . . 428 Creating the Designer . . .432 Building the Designer . . . 435 Adding Items to Your Designer . . . 439 Adding Domain Properties . . . 440 Adding an Enumerated Data Type . . . 441 Adding Relationships to Support Connections . . . 441 Adding Graphical Items . . . 442 Adding Toolbox Items . . . 446 Validation, Generation, and Test . . . 447 Enhancing Model Validation . . .450 Enabling Validation . . . 450 Adding Validation Code . . . 452 Other Options . . . 454 Generating Code . . . 454 Configuring the Template . . . 455 Distributing Your Designer . . . 458 Converting the Template to a Custom Tool: Visual Studio 2005/2008 . . .459 Preloading the Custom Tool Property . . .462 Create a Deployment Project: Visual Studio 2005/2008 . . . 464 Deploying: VS2010 . . .465 Visual Studio 2010 Additions . . .  465 Capturing Inputs . . . 466 PART III: APPENDIXES . . . 467 Appendix A Generating Menu Names . . .468 Appendix B Options Dialog Categories, Subcategories, and Properties . . . 469 Appendix C A Code-Generation Add-In . . . 470 Integrating Code-Generation Classes . . . 470 Adding the Submenu Button . . . 471 Responding to Events . . . 475 Responding to the Menu Button . . . 479 An Extensible Solution . . . 479 Appendix D Distributing Code-Generation Solutions . . . 481 Creating the .vscontent File . . . 481 Adding Add-Ins . . . 482 Adding Templates . . . 482 Adding a Toolbox Control . . .484 Adding Files . . . 484 A Complete Example . . .485 Installing the Solution . . .486 Index . . . 487