The XNA Framework Content Pipeline (Content Pipeline) is a customizable tool included in XNA Game Studio (XGS) for preparing digital content to be used in your games. The XNA Team Blog has an entry here that describes the Content Pipeline, and there are several tutorials and samples on the XNA Creators Club Online web site that explain how to extend the Content Pipeline with your own custom content importers and processors. Although it is easy to add custom extensions, many people find it difficult to debug their custom components as they develop them. In this post, I'm going to explain what makes them so hard to debug, and later I'll provide instructions on how to set up your Visual Studio or Visual C# Express development environment to make debugging them as easy as pressing F5.

A number of people have asked me why they can't hit breakpoints or stop on exceptions in their Content Pipeline Extension Library projects when they debug a game project that uses it. To me, this is a bit like asking why a car doesn't fly when you drive it to the airport. It's hard to answer in a way that will lead to understanding, because I don't know why anyone would expect such a thing. Even though your trip involves flying, you don't fly during every part of the trip. Maybe it's best to start at the beginning.

The Start Debugging command does a lot of things. In most cases, developers don't need to know or think about what those things are, because the end result is usually what they want: they get to debug their code. When that doesn't happen, it helps to know what is expected before trying to identify what went wrong.

When you press F5 in Visual Studio (the common shortcut for Start Debugging), the following things happen:

1. The IDE determines whether any files need to be saved, and takes the appropriate action.
2. The IDE determines which projects to build, as well as which project configuration to build.
3. The IDE chooses an order in which to build the projects, based on the project dependencies.
4. The IDE builds each project selected in step 2, individually for its selected configuration, in the order computed in step 3.
5. The IDE determines which projects to deploy (this applies to Xbox 360 projects, but not Windows projects).
6. The IDE deploys all projects that were identified in step 5.
7. The IDE determines which programs to start.
8. The IDE launches each program identified in step 7, with the debugger attached.

There are a number of ways this can be customized.

• Step 1: The default is to save all files, but you can change the behavior in Tools Options.
• Step 2: The default is to build all projects with a project configuration that matches the active solution configuration, but this can be customized in many ways.
• Configuration Manager allows you to edit solution configurations, which are lists of projects and configurations to be built when the solution configuration is active.
• There is also a command that will limit the solution build to only the Startup Project and its dependencies.
• There is an option to prompt to build deployable projects that are out of date, but otherwise not selected to be built.
• Step 3: Project dependencies are usually determined by project-to-project references, but you can add additional dependencies using the Project Dependencies dialog box. This information is stored in the solution file.
• Step 4: See steps 2 and 3.
• Step 5: You can customize which projects to deploy by editing solution configurations in Configuration Manager, and by changing the active solution configuration.
• Step 6: See step 5.
• Step 7: The default is to have only one startup project for a solution, but there is an option to have multiple startup projects in one solution.
• A startup project can be configured to launch its output EXE, if it is an EXE project.
• A startup project can also be configured to launch another application (option not available in VC# Express).
• Step 8: The IDE will start all startup projects and attach the debugger to each one so that you debug them all simultaneously. (Many developers do not realize that you can debug more than one application at once with the same IDE.)

Okay, now that I've given a summary of what F5 does, let's study a particular example to see why breakpoints in a Content Pipeline Extension Library project are never hit.

Let's consider the Custom Model Importer Sample from the Creators Club Online web site.

In this sample solution, there are two projects: one Windows Game (2.0) project, called ObjImporterGameWindows, and one Content Pipeline Extension Library (2.0) project, called ObjImporter.

When I load this sample project and press F5, the following things are going to happen:

1. No files are dirty, so nothing needs to be saved.
2. The active solution configuration is "Debug|x86", and that solution configuration says that both ObjImporter and ObjImporterGameWindows should be built using their respective "Debug|x86" project configurations.
3. ObjImporter is determined to build first, since ObjImporterGameWindows has an indirect dependency on it through its nested Content project.
4. The projects are built:
1. ObjImporter is built for "Debug|x86", producing ObjImporter.dll.
2. ObjImporterGameWindows is built for "Debug|x86"
1. Before the code is built, ObjImporterGameWindows forces the Content subproject to build.
2. When the Content subproject builds, the Content Pipeline loads the ObjImporter.dll from step 4.2.1 and uses it to build the Tank.obj model.
3. After the Content subproject is finished building, the code in ObjImporterGameWindows is built, producing ObjImporterGameWindows.exe.
5. No projects are deployable.
6. Deployment is skipped.
7. ObjImporterGameWindows is the startup project, so ObjImporterGameWindows.exe is that application to start.
8. The IDE launches ObjImporterGameWindows.exe under the debugger.

Now that we've covered the whole Start Debugging process in detail, it's a lot easier to answer the original question, "Why don't I hit breakpoints in my Content Pipeline Extension Library project when I press F5?"

Answer: Debugging doesn't start until step 8, but the ObjImporter.dll library is loaded up and executed in step 4.

When you start debugging in the IDE, you aren't going to hit breakpoints just because they are set. You will only hit them if you debug a process that loads the corresponding binary, and the debugger can find symbols (.pdb file) that says a loaded binary came from that source file.

In the case of a Windows game, you don't start debugging until after the game EXE has been built. By that time, the Content Pipeline is already done its work. Since the breakpoints correspond to ObjImporter.dll, you won't ever hit them this way.

If you want to debug the ObjImporter.dll as it runs in the Content Pipeline, you need to debug something other than your game project. In my next post, I'll explain how to set up a solution so that F5 will debug the Content Pipeline instead of your game.