For the past 7 years, the DotNetNuke project has provided various packages for users to simplify different installation and upgrade scenarios. Each package was built to address specific requests from the community. We have recently begun receiving requests for symbol files (.pdb files) and xml comments. As a result of these requests, starting with DotNetNuke 5.2.0, we will be releasing a new Symbols package with each release.
The first set of files included in the Symbols package are all of the .PDB files for the core framework. Essentially, any project which is included in the default solution file will generate a .pdb file that will be available in this package. Many developers have long assumed that .pdb files were only generated for debug builds, however, that does not have to be the case. It is possible, and even desirable, to generate .pdb files for release builds as well. To generate the pdb files follow the steps outlined below:
- Open the Project Properties
- Select the Compile tab
- Set the configuration mode to Release
- Click on the Advanced Compile Options button
- Set the “Generate debug info” to “pdb-only”
You should see a screen similar to the image below.
Most users will never need the pdb files for their installation, however, if you are troubleshooting error messages in your event log then the pdb files will provide additional information which can aids in troubleshooting. To see how pdb files can help, lets look at a sample error message from the event log:
While there is some useful information in this error message in the stack trace, it just gives you a list of classes and methods to look through. If your methods are not granular enough, just knowing the method may not be enough. If you have installed the pdb files into your DotNetNuke installation then you will receive additional information in your stack trace as shown below.
Notice in the highlighted section that I now have an exact line number where the error occurred in the DotNetNuke source code. This greatly simplifies identifying the root cause of errors and makes it much easier to take corrective action. This is just one of the uses for pdb files, but is a great benefit when trying to isolate and troubleshoot problems in a production environment
In addition to symbol files, the new Symbols package will include XML Comments that are generated as part of the build process. The XML Comments will be used in the near future to create detailed API documentation for the core DotNetNuke framework. In addition to their usefulness in creating documentation, they are also useful when you are writing code that uses the core API. Lisa Feigenbaum has a great article in the May 2009 issue of MSDN magazine that fully explains the benefits of the XML Comments files.
Over the coming months, the new DotNetNuke Reference team will be going through and helping to get the core framework documented with XML Comments. This will allow us to provide more useful Intellisense and complete API reference documentation that also includes code samples for how to use various portions of the API.
The first version of the Symbols package which was released today along with DotNetNuke 5.2.0 Beta 5 requires you to unzip the files over the top of your existing DotNetNuke installation. It doesn’t matter if you are using the Install, Upgrade, Source, or StarterKit package for creating your DotNetNuke installation. The only requirement is that the Symbol files are only valid for the specific version where they were generated. This means that you cannot use the 5.2.0 Beta 5 symbols with any release other than Beta 5.
We are working on updating the Symbols package so that in the final 5.2.0 release you will be able to install and uninstall the Symbols package from the Host/Extensions page. This will make it possible to install Symbols for any installation where you have host access, even if you don’t have full access to the file system for directly uploading files.
In the end, I think this is a good addition to the current set of packages we already provide. For those who care about symbol files and intellisense, you will be able to use them without much difficulty and install them with whatever package you prefer to use. For those people who don’t want them, you will be able to continue using the same packages you always have without any size bloat from files which you don’t want.