Pro NuGet Second Edition Maarten Balliauw Xavier Decoster
Contents About the Authors About the Technical Reviewers Foreword The Bigger Picture xvii xix xxi xxiii (^Chapter 1: Getting Started 1 Preparing Your Workstation 1 Supported Development Environments 1 Installing the Essential Software 2 Installing NuGet 5 Installing the NuGet Visual Studio Extension (Visual Studio 2010) 5 Updating the NuGet Visual Studio Extension (Visual Studio 2012) 7 Downloading the NuGet Command-Line Tool 7 Installing NuGet Package Explorer 8 Downloading Development Builds 9 Getting Further Information 10 Summary 11 SChapter 2: Consuming and Managing Packages in a Solution 13 Consuming Your First NuGet Package 13 Integrating Visual Studio and NuGet 14 Finding the Package You Need 15 Installing a NuGet Package 18 Uninstalling a Package 20 Updating a Package to the LatestVersion 21 vii
Using the Package Manager Console 23 Finding a Specific Version of a Package 25 Installing a Specific Version of a Package 26 Uninstalling a Package 27 Updating a Package to a Newer Version 27 Using the Package Manager Console Default Project 29 Reinstalling Packages 29 Using the NuGet Command Line 30 Installing a Package 31 Updating a Package 33 Uninstalling a Package 33 Managing Packages in a Solution 34 Installing Packages in Multiple Projects 34 Uninstalling Packages from Multiple Projects 37 Updating Packages in Multiple Projects 39 Visualizing Package Dependencies by Using the Package Visualizer 40 Working with Package Sources and the Package Cache 42 Managing Package Sources 43 How the Cache Impacts Package Installation 44 Authenticating Package Sources 44 Choosing Stable vs. Prerelease Versions 45 Summary 46 Chapter 3: Authoring Packages 47 Understanding Package Definition Strategies 47 Creating a Simple Package Manifest 48 Exposing Package Metadata 49 Specifying the Package Contents 57 Package Versioning 68 Nuspec Inheritance 73 viii
Creating Packages by Using the NuGet Command Line 73 Creating a Package from a Convention-Based Directory 73 Creating a Package from an Assembly 76 Creating a Package from a Visual Studio Project 77 Creating Packages by Using NuGet Package Explorer 82 Creating Localized Packages 86 Setting the Default Language 87 Using a Single-Package Approach 87 Using a Satellite-Package Approach 88 Comparing Approaches 89 Adding the Finishing Touches 90 Provide a Smooth User Experience 90 Learn from Others by Inspecting Their Packages 91 Design from a Consumer's Perspective 93 Provide a Sample Package 94 Testing Packages 96 Summary 97 Chapter 4: Publishing Packages 99 Creating a Sample Package 99 Contributing to nuget.org 102 Creating an Account 103 Publishing a NuGet Package 104 Managing Published Packages 106 Obtaining an API Key 107 Publishing Packages by Using the NuGet Command Line 108 Publishing a Package to a NuGet Feed 108 Managing API Keys 110 Publishing Packages by Using NuGet Package Explorer 110 ix
Publishing a Symbol Package 112 Configuring Visual Studio 112 Consuming Symbols for NuGet Packages 114 Publishing Symbols for Your Own NuGet Packages 116 Summary 116 Chapter 5: Hosting Your Own NuGet Server 117 Why Host Your Own NuGet Feed? 117 Setting Up a Simple NuGet Package Repository 118 Creating a Basic NuGet Server 120 Configuring the Packages' Location 126 Setting the API Key 127 Using the NuGet Gallery 128 Downloading the Source Code 128 Creating a SQL Server Database 129 Configuring NuGet Gallery 129 Compiling NuGet Gallery 130 Finalizing Your NuGet Gallery Installation 132 Using NuGet as a Service: MyGet...133 Creating a NuGet Feed on MyGet 133 Mirroring Packages from the Official NuGet Package Source 138 Applying Security Settings to Your Feed 143 What Else Is There? 147 Using ProGet 148 Downloading and Installing ProGet 148 Consuming NuGet Packages by Using ProGet 149 Adding Your Own NuGet Packages 151 What Else Is There? 152 X
Using TeamCity as a NuGet Repository 152 Pushing Packages to a NuGet Feed 153 Exposing Build Artifacts by Using TeamCity's NuGet Feed 154 Using Other NuGet Repositories 156 Preventing Disruptions in the Continuum 157 Summary 157 Chapter 6: Continuous Package Integration 159 Using a No-Commit Strategy 159 Source Control Layout 160 Exploring Trade-offs 164 Tracking Package Metadata 166 Enabling Package Restore 167 Promoting Packages 173 Prereleasing Packages 174 Phasing Out Packages 175 Summary 177 M Chapter 7: Automated Delivery 179 Deploying Artifacts with Octopus Deploy 179 What Is Octopus Deploy? 180 Installing Octopus Deploy 180 Deploying a Project by Using Octopus Deploy 185 Deploying Software with Chocolatey 199 What Is Chocolatey? 200 Installing Chocolatey 200 Using Chocolatey 204 Distributing Chocolatey Goodness 211 Summary 214 xi
Chapter 8: NuGet Recipes 215 Team Foundation Server/Service 215 Working with NuGet package restore 221 Creating and Publishing NuGet packages during a build 222 TeamCity 223 Installing NuGet to TeamCity Build Agents 223 NuGet Build Runners 224 Enabling the TeamCity NuGet feed 231 TeamCity and OctopusDeploy 233 Windows Azure Web Sites and NuGet Package Restore 235 Creating and Configuring the Windows Azure Web Site for Auto-Deployment from GitHub 235 Configuring NuGet Package Restore from a Secured Feed 239 NuGet and MyGet 242 Using MyGet Build Services 242 Continuous Delivery of NuGet packages 243 Working with aggregate feeds 251 Setting up a Private Symbol Server 252 Installing prerequisites 253 Setting up the Symbol Server 254 Pushing Symbols 256 Consuming Symbols 256 Package Source Discovery 257 Summary 258 Chapter 9: Extending NuGet 259 Why Extend NuGet? 259 Extending the NuGet Command Line 260 Creating a Custom NuGet Command 261 Installing a Custom NuGet Command 263 Creating Custom Package Analysis Rules 265 xii
Extending the Package Manager Console 268 Creating and Distributing a Package Manager Console Extension 268 Adding Tab Expansions to Package Manager Console Extensions 273 Extending NuGet Package Explorer 277 Creating a Custom Content Viewer 279 Creating a Custom Package Validation Rule 281 Creating a Custom Package Command 283 Invoking NuGet Services from Inside Visual Studio 285 Summary 285 Chapter 10: NuGet as a Protocol 287 Understanding Protocols 287 Creating a Pluggable Application by Using NuGet 288 Defining Architecture and Technologies 292 Defining the ISearchEngine Interface 293 Importing Search Engines 294 Installing Plug-ins into SearchPortal 296 Loading Installed Plug-ins into MEF's Catalog 301 Creating and Publishing Plug-ins 302 Creating a Self-Updating Application by Using NuGet 303 The NuGet Command Line as Example 303 An Application Bootstrapper That Checks for Updates 305 Summary 307 Appendix A: Package Manifest Reference 309 Creating the Metadata Section 309 Package Manifest Metadata elements 309 Populating Replacement Tokens 311 Referencing Dependencies 312 Specifying Dependencies 312 Specifying Explicit Assembly References 314 Specifying Framework Assembly References from the GAC 315 xiii
Specifying Files to Include in a Package 315 Exploring File Element Examples 316 Excluding Files from the Package Manifest 319 ^Appendix B: NuGet Command-Line Reference 321 The help Command 321 The config Command 321 The delete Command 322 The install Command 323 The list Command 324 The pack Command 324 The push Command 325 The restore Command (NuGet >2.7) 326 The setapikey Command 327 The sources Command 327 The spec Command 328 The update Command 328 ^Appendix C: NuGet Package Manager Console PowerShell Reference 331 Support for Common Parameters 331 Adding Binding Redirects 332 Getting a Package or a Set of Packages 332 Getting Project Information 333 Installing Packages 334 Opening Package Pages 335 Uninstalling Packages 335 Updating Packages 336 Chaining PowerShell Cmdlets 337 xiv
HAppendix D: NuGet Configuration File Reference 339 Configuration File Locations 339 Which File Will NuGet Use? 340 Useful Scenarios 341 Configuration File 342 Index 347 XV