Microsoft Inside the Microsoft* Build Engine: Using MSBuild and Team Foundation Build, Second Edition Sayed Hashimi William Bartholomew
Table of Contents Foreword x'x Introduction x*1 Part I Overview 1 MSBuild Quick Start 3 Project File Details 3 Properties and Targets 4 Items 9 Item Metadata H Simple Conditions 15 Default/Initial Targets 17 MSBuild.exe Command-Line Usage 18 Extending the Build Process 21 2 MSBuild Deep Dive, Part 1 23 Properties 24 Environment Variables 26 Reserved Properties 27 Command-Line Properties 30 Dynamic Properties 32 Items 34 Copy Task 36 Weil-Known Item Metadata 41 Custom Metadata 44 Item Transformations 47
Table of Contents 3 MSBuild Deep Dive, Part 2 53 Dynamic Properties and Items 53 Dynamic Properties and Items: MSBuild 3.5 53 Property and Item Evaluation 60 Importing Files 64 Extending the Build Process 69 Property Functions and Item Functions 77 Property Functions 77 String Property Functions 78 Static Property Functions 79 MSBuild Property Functions 80 Item Functions 82 Part ii Customizing MSBuild 4 Custom Tasks 87 Custom Task Requirements 87 Creating Your First Task 88 Task Input/Output 91 Supported Task Input and Output Types 95 Using Arrays with Task Inputs and Outputs 97 Inline Tasks 101 TaskFactory HI Extending ToolTask 116 ToolTask Methods 118 ToolTask Properties 119 Debugging Tasks 124 5 Custom Loggers 129 Overview 129 Console Logger 130 File Logger 132 ILogger Interface 134 Creating Custom Loggers 135 Extending the Logger Abstract Class 140 Extending Existing Loggers 146 FileLoggerBase and XmlLogger 151 Debugging Loggers 157
Part ill Advanced MSBuild Topics 6 Batching and Incremental Builds 163 Batching Overview 163 Task Batching 166 Target Batching 170 Combining Task and Target Batching 172 Multi-batching 175 Using Batching to Build Multiple Configurations 177 Batching Using Multiple Expressions 181 Batching Using Shared Metadata 183 Incremental Building 188 Partially Building Targets 190 7 External Tools 193 Exec Task 193 MSBuild Task 197 MSBuild and Visual Studio Known Error Message Formats 203 Creating Reusable Build Elements 204 NUnit 206 FxCop 215 Part iv MSBuild Cookbook 8 Practical Applications, Part 1 223 Setting the Assembly Version 223 Building Multiple Projects 225 Attaching Multiple File Loggers 231 Creating a Logger Macro 232 Custom Before/After Build Steps in the Build Lab 233 Handling Errors 235 Replacing Values in Config Files 237 Extending the Clean 239 9 Practical Applications, Part 2 245 Starting and Stopping Services 245 Web Deployment Project Overview 246 Zipping Output Files, Then Uploading to an FTP Site 252
Compressing JavaScript Files 254 Encrypting web.config 256 Building Dependent Projects 258 Deployment Using Web Deployment Projects 260 Partv MSBuild in Visual C++ 2010 10 MSBuild in Visual C++ 2010, Part 1 267 The New.vcxproj Project File 267 Anatomy of the Visual C++ Build Process 269 Diagnostic Output 271 Build Parallelism 272 Configuring Project- and File-Level Build Parallelism 273 File Tracker-Based Incremental Build 279 Incremental Build 279 File Tracker 279 Trust Visual C++ Incremental Build 281 Troubleshooting 281 Property Sheets 281 System Property Sheets and User Property Sheets 284 Visual C++ Directories 285 11 MSBuild in Visual C++ 2010, Part 2 289 Property Pages 289 Reading and Writing Property Values 289 Build Customizations 294 Platforms and Platform Toolsets 297 Native and Managed Multi-targeting 300 Native Multi-targeting 300 How Does Native Multi-targeting Work? 301 Managed Multi-targeting 301 Default Visual C++ Tasks and Targets 302 Default Visual C++ Tasks 303 Default Visual C++ Targets 303 ImportBefore, ImportAfter, ForcelmportBeforeCppTargets, and ForcelmportAfterCppTargets 306 Default Visual C++ Property Sheets 307
Migrating from Visual C++ 2008 and Earlier to Visual C++ 2010 311 IDE Conversion 311 Command-Line Conversion 314 Summary 315 12 Extending Visual C++ 2010 317 Build Events, Custom Build Steps, and the Custom Build Tool 317 Build Events 317 Custom Build Step 319 Custom Build Tool 322 Adding a Custom Target to the Build 324 Creating a New Property Page 326 Troubleshooting 331 Creating a Build Customization 332 Adding a New Platform and Platform Toolset 338 Deploying Your Extensions 342 Part vi Team Foundation Build 13 Team Build Quick Start 347 Introduction to Team Build 347 Team Build Features 347 High-Level Architecture 348 Preparing for Team Build 350 Team Build Deployment Topologies 350 What Makes a Good Build Machine? 351 Installing Team Build on the Team Foundation Server 352 Setting Up a Build Controller 352 Setting Up a Build Agent 355 Drop Folders 359 Creating a Build Definition 360 General 360 Trigger 361 Workspace 365 Build Defaults 367 Process 368 Retention Policy 369
Working with Build Queues and History 371 Visual Studio 372 Working with Builds from the Command Line 383 Team Build Security 388 Service Accounts 388 Permissions 391 Team Build Deep Dive 395 Process Templates 395 Default Template 396 Logging 396 Build Number 397 Agent Reservation 398 Clean 399 Sync 400 Label 400 Compile and Test 401 Source Indexing and Symbol Publishing 404 Associate Changesets and Work Items 407 Copy Files to the Drop Location 407 Revert Files and Check in Gated Changes 409 Create Work Items for Build Failure 409 Configuring the Team Build Service 409 Changing Communications Ports 409 Requiring SSL 410 Running Interactively 411 Running Multiple Build Agents 412 Build Controller Concurrency 413 Team Build API 414 Creating a Project 414 Connecting to Team Project Collection 415 Connecting to Team Build 416 Working with Build Service Hosts 416 Working with Build Definitions 417 Working with Builds 419 Workflow Foundation Quick Start 423 Introduction to Workflow Foundation 423 Types of Workflows 423
Building a Simple Workflow Application 424 Workflow Design 426 Built-in Activities 426 Working with Data 428 Exception Handling 430 Custom Activities 433 Workflow Extensions 437 Persistence 437 Tracking 437 Putting It All Together Workflow Foundation Image Resizer Sample Application 438 Overview 438 Building the Application 438 Running the Application 452 Debugging the Application 452 Summary 453 16 Process Template Customization 455 Getting Started 455 Creating a Process Template Library 455 Creating a Custom Activity Library 460 Process Parameters 461 Defining 451 Metadata 463 User Interface 466 Supported Reasons 468 Backward and Forward Compatibility 469 Team Build Activities 469 AgentScope 469 ChecklnGatedChanges 470 ConvertWorkspaceltem/ConvertWorkspaceltems 470 ExpandEnvironmentVariables 470 FindMatchingFiles 470 GetBuildAgent 471 GetBuildDetail 471 GetBuildDirectory 471 GetBuildEnvironment 471 GetTeamProjectCollection 471 InvokeForReason 471
Table of Contents InvokeProcess 471 MSBuild 472 SetBuildProperties 472 SharedResourceScope 473 UpdateBuildNumber 473 Custom Activities 473 BuildActivity Attribute 473 Extensions 474 Logging 475 Logging Verbosity 475 Logging Activities 476 Logging Programmatically 477 Adding Hyperlinks 478 Exceptions 482 Deploying 482 Process Templates 482 Custom Assemblies 483 Downloading and Loading Dependent Assemblies 485 Part vii Web Development Tool 17 Web Deployment Tool, Part 1 489 Web Deployment Tool Overview 490 Working with Web Packages 490 Package Creation 492 Installing Packages 494 msdeploy.exe Usage Options 498 MSDeploy Providers 500 MSDeploy Rules 504 MSDeploy Parameters 510 -declareparam 513 -setparam 515 MSDeploy Manifest Provider 517 18 Web Deployment Tool, Part 2 521 Web Publishing Pipeline Overview 521 XML Document Transformations 521
Web Publishing Pipeline Phases 530 Excluding Files 533 including Additional Files 536 Database 539 19 Web Deployment Tool Practical Applications 545 Publishing Using MSBuild 545 Parameterizing Packages 550 Using -setparamfile 554 Using the MSDeploy Temp Agent 556 Deploying Your Site from Team Build 557 Deploying to Multiple Destinations Using Team Build 560 Excluding ACLs from the Package 565 Synchronizing an Application to Another Server 566 Index 589 Appendix A New Features in MSBuild 4.0 (available online) 569 Appendix B Appendix C Building Large Source Trees (available online) 579 Upgrading from Team Foundation Build 2008 (available online) 585