BuildDocProject failed on fresh June CTP/1.6.1 install

Topics: Bugs, General Discussion, General Questions, Sandcastle
Jun 25, 2007 at 1:11 AM
I just installed SandCastle June CTP and DocProject 1.6.1. After creating a fresh doc project, I tried to build it and got the following:

The "BuildDocProject" task failed unexpectedly.
System.NullReferenceException: Object reference not set to an instance of an object.
at System.Configuration.ConfigurationElementCollection.BaseGet(Object key)
at DaveSexton.DocProject.Sandcastle.Configuration.PresentationCollection.get_Item(String name)
at DaveSexton.DocProject.Sandcastle.SandcastleSettings..ctor(IBuildEngine engine)
at DaveSexton.DocProject.Sandcastle.SandcastleBuildEngineProvider.CreateBuildSettings(IBuildEngine engine)
at DaveSexton.DocProject.Engine.BuildEngine`2.get_Settings()
at DaveSexton.DocProject.Engine.BuildEngine`2.Build()
at DaveSexton.DocProject.BuildController.Build(IDocProject project, BuildType buildType)
at DaveSexton.DocProject.BuildController.Build(IDocProject project)
at DaveSexton.DocProject.MSBuild.BuildDocProject.Execute()
at Microsoft.Build.BuildEngine.TaskEngine.ExecuteTask(ExecutionMode howToExecuteTask, Hashtable projectItemsAvailableToTask, BuildPropertyGroup projectPropertiesAvailableToTask, Boolean& taskClassWasFound)


Any suggestions?
Jun 25, 2007 at 3:19 AM
Hi,

Make sure that you've created a new DocProject for the 1.6.1 version since older versions may not be compatible.

The error is strange since it's occurring in framework code. I used .NET Reflector to look at that source code for ConfigurationElementCollection.BaseGet(Object) in the .NET Framework 2.0 and it appears that the only way NullReferenceException would be thrown is if the local entry variable is null. The MSDN documentation does not indicate that BaseGet may throw NullReferenceException. Uh oh!

Well, maybe you wouldn't mind attaching a debugger with DocProject's source code to verify the application's state at the time of the error?

If so, check out How To Use The Source Code first. Then, once you've gotten the solution to build successfully, configure Visual Studio to automatically break on an unhandled NullReferenceException or, alternatively, add a breakpoint in the DaveSexton.DocProject.Sandcastle.SandcastleSettings constructor (found in the DaveSexton.DocProject.Sandcastle project) so that you can step until the exception is thrown. Once you're ready press F5 to build and attach the debugger to a new instance of Visual Studio 2005. Load your project and do what you did before so that the exception occurs again.

What I'd like to know at the time of the exception is the current line number and the values for the local variables. It may be especially helpful to know the value of the key being read too.

If you need any help with the source code just ask.

Thanks,
Dave
Jun 25, 2007 at 2:52 PM
Dave,

I was able to get DocProject built, but not until I added a reference to Interop.MsHelpCompiler, while there is still a broken reference to an MsHelpCompiler activeX listed as well and I get warnings about

"The referenced component 'MSHelpCompiler' could not be found."
and
"Cannot load type library for reference "MSHelpCompiler". Library not registered. (Exception from HRESULT: 0x8002801D (TYPEELIBNOTREGISTERED))"

But beyond that, the problems is that the exception occurs on build/rebuild/clean. So there isn't really an F5 scenario in which I can intercept the exception, it always seems to get swallowed by Visual Studio. If you know how to intercept exceptions thrown by the build process, let me know.

thanks,
arne


Jun 25, 2007 at 3:23 PM
Apparently DocProject in general has that problem. I tried a brand new project and had the same error. I thought I might tweak some settings only to discover that the buttons installed both come up with a Command Execution Error "Object reference not set to an instance of an object", i.e. that NullReferenceException again
Jun 25, 2007 at 6:47 PM
Hi Arne,

Thanks for the reply.


I was able to get DocProject built, but not until I added a reference to Interop.MsHelpCompiler, while there is still a broken reference to an MsHelpCompiler activeX listed as well

I'm not sure that I understand. DocProject does reference Interop.MSHelpCompiler. But I'm glad that you got it built anyway :)


and I get warnings about

"The referenced component 'MSHelpCompiler' could not be found."
and
"Cannot load type library for reference "MSHelpCompiler". Library not registered. (Exception from HRESULT: 0x8002801D (TYPEELIBNOTREGISTERED))"

Ok, it sounds to me like you didn't install the Visual Studio 2005 SDK? To use the source code I recommended installing all of DocProject's prerequisites.


But beyond that, the problems is that the exception occurs on build/rebuild/clean. So there isn't really an F5 scenario in which I can intercept the exception, it always seems to get swallowed by Visual Studio. If you know how to intercept exceptions thrown by the build process, let me know.


Well, you can put a break point on the SandcastleSettings constructor since your stack trace shows that the exception is occurring in a method call there.

An alternative is to open Debug > Exceptions and then check Common Language Runtime Exceptions - Thrown,

If you've followed the instructions in How To Use The Source Code, Testing the Solution then you should be able to hit F5 and have Visual Studio attach to another instance of Visual Studio.


Apparently DocProject in general has that problem. I tried a brand new project and had the same error. I thought I might tweak some settings only to discover that the buttons installed both come up with a Command Execution Error "Object reference not set to an instance of an object", i.e. that NullReferenceException again


What version of Visual Studio are you using and do you have any Orcas CTP? Do you have any special modifications to framework code? Open-source stuff? Special patches?

I ask because it sounds like there is a bug in the framework code. According to your original stack trace the exception is a NullReferenceException occurring in the method of a collection class. That just sounds like a bug to me.

Thanks,
Dave
Jun 25, 2007 at 7:27 PM
Hi Arne,

I deleted the last post because I just discovered something more important

I went back and looked at the framework's code again. It appears that a NullReferenceException can be thrown if the specified key is null, although it really should be explicitly throwing an ArgumentNullException :) Anwyay, now I think that DocProject might be passing in a null key.

In DocProject's source it appears that the problem may be with the presentation's name. It sounds like DocProject cannot discover your project's presentation and for some reason is using null instead. Would you mind posting your .csproj or .vbproj for your DocProject or DocSite here?

Thanks,
Dave
Jun 25, 2007 at 9:09 PM
Dave,

I created a new sample solution just to make sure there wasn't something funky about it. Here's the csproj for the DocProject for that sample solution:

<Project DefaultTargets="BuildHelp" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
<Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
<ProductVersion>8.0.50727</ProductVersion>
<SchemaVersion>2.0</SchemaVersion>
<ProjectGuid>{3CA89D38-CC30-48EB-84E2-662533A12588}</ProjectGuid>
<OutputType>Library</OutputType>
<RootNamespace>Doc</RootNamespace>
<AssemblyName>Doc</AssemblyName>
<RunPostBuildEvent>Always</RunPostBuildEvent>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
<DebugSymbols>true</DebugSymbols>
<DebugType>full</DebugType>
<Optimize>false</Optimize>
<OutputPath>bin\Debug\</OutputPath>
<DefineConstants>DEBUG;TRACE</DefineConstants>
<ErrorReport>prompt</ErrorReport>
<WarningLevel>4</WarningLevel>
<UseVSHostingProcess>false</UseVSHostingProcess>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
<DebugType>pdbonly</DebugType>
<Optimize>true</Optimize>
<OutputPath>bin\Release\</OutputPath>
<DefineConstants>TRACE</DefineConstants>
<ErrorReport>prompt</ErrorReport>
<WarningLevel>4</WarningLevel>
</PropertyGroup>
<Import Project="$(MSBuildBinPath)\Microsoft.CSharp.targets" />
<Import Project="$(DocProjectBuildPath)\DaveSexton.DocProject.targets" />
<!-- To modify your build process, add your task inside one of the targets below and uncomment it.
Other similar extension points exist, see Microsoft.Common.targets.
<Target Name="BeforeBuild">
</Target>
<Target Name="AfterBuild">
</Target>
-->
<ItemGroup>
<Compile Include="Properties\AssemblyInfo.cs" />
</ItemGroup>
<ProjectExtensions>
<VisualStudio>
<UserProperties IsDocProject="true" ProcessComponentTypeName="Doc.BuildProcess" />
</VisualStudio>
</ProjectExtensions>
<ItemGroup>
<Reference Include="DaveSexton.DocProject, Version=1.6.1.0, Culture=neutral, PublicKeyToken=af1a4bab65cc4ece, processorArchitecture=MSIL">
<SpecificVersion>False</SpecificVersion>
</Reference>
<Reference Include="System" />
</ItemGroup>
<ItemGroup>
<Compile Include="BuildProcess.cs" />
</ItemGroup>
<ItemGroup>
<None Include="Presentation\Shared\configuration\xamlSyntax.config" />
</ItemGroup>
<ItemGroup>
<Content Include="Presentation\Shared\content\syntax_content.xml" />
<Content Include="Presentation\Shared\scripts\copycode.js" />
<Content Include="Presentation\Shared\scripts\samples.js" />
<Content Include="Presentation\Shared\transforms\utilities_dduexml.xsl" />
<Content Include="Presentation\Shared\transforms\utilities_metadata.xsl" />
<Content Include="Presentation\Shared\transforms\utilities_reference.xsl" />
<Content Include="Presentation\Style\project.xml" />
</ItemGroup>
<ItemGroup>
<Folder Include="Icons\" />
<Folder Include="Presentation\Style\Content\" />
<Folder Include="Presentation\Style\Transforms\" />
<Folder Include="Scripts\" />
<Folder Include="Styles\" />
</ItemGroup>
</Project>

To answer your previous question, here's my environment:
VS2k5 8.0.50727.762 (SP.050727-7600)
.NET 2.0.50727

I installed SP1 before i installed Sandcastle and DocProject and my machine also has the most recent Orcas on it.

In the meantime, i'll go back to the instructions for testing the source and see if i can run that through it's proper paces
Jun 25, 2007 at 9:31 PM
Hi,

Thanks for posting your project file. I've identified the problem in it:

<ProjectExtensions>
  <VisualStudio>
    <UserProperties IsDocProject="true" ProcessComponentTypeName="Doc.BuildProcess" />
  </VisualStudio>
</ProjectExtensions>
This area is where DocProject stores your project's settings. The error is occurring because your DocProject is missing some required attributes, such as BuildEngineProviderName and Sandcastle_PresentationName.

When you create a new DocProject a wizard runs to configure the project. This wizard is required and will warn you if you attempt to close it without finishing.

Did you see the wizard?
Did you select your project's build engine and presentation style from the drop-down list in one of the wizard steps?
Did you complete the wizard?

Thanks,
Dave
Jun 25, 2007 at 9:40 PM
I get the same error and have the same project settings. I complete the wizard and just choose the defaults. I was able to create a website, but not the product documentation.
Jun 25, 2007 at 10:35 PM
Edited Jun 25, 2007 at 10:40 PM
Hi bclubb,

Thanks for the feedback.

If you clicked OK on the wizard then DocProject will call EnvDTE.Project.Save(null) to commit the changes to disc. These changes are supposed to include all of the persistable EnvDTE.Globals settings that DocProject uses.

In your case (and probably Arne's too) it seems that Visual Studio is not saving the project settings to the file like it should.

I'm not really sure how to debug this. Maybe one of you would be willing to try running the following code in a macro to at least verify whether your version of Visual Studio uses the Globals object appropriately:

 
Public Sub TestGlobals()
  Dim name as String = "solution_name\project_name.csproj"
 
  Dim project As Project = DTE.Solution.Projects.Item(name)
  project.Globals.VariableValue("Test") = "a value"
  project.Globals.VariablePersists("Test") = True
  project.Save()
End Sub
To use this macro:
  1. Create a new solution and add a new C# console application project.
    1. Edit: Save the project to disc before continuing.
  2. Open Tools > Macros > Macros IDE...
  3. Add a new Module to MyMacros and name it DocProject.
  4. Open the new module by double-clicking it.
  5. Add the code snippet from above and set the name variable with the appropriate value.
  6. Save the macro.
  7. Go back to Visual Studio's main IDE.
  8. Press Ctrl+Alt+A to open the command window.
  9. Type Macros.MyMacros.DocProject.TestGlobals and press enter.
  10. Right-mouse click the project node in Solution Explorer and select Unload Project
  11. Right-mouse click the project node again and select Edit to open the project file.
You should see the following if it worked:

  <ProjectExtensions>
    <VisualStudio>
      <UserProperties Test="a value" />
    </VisualStudio>
  </ProjectExtensions>
If it doesn't work then you may have found a bug in Visual Studio. If it does work then we'll proceed from here.

Thanks,
Dave
Jun 25, 2007 at 10:50 PM
When I run that macro, I get a dialog with "Value does not fall within the expected range."

Since you mentioned earlier that my issues with building the DovProject solution is related to my missing the VS 2005 SDK, i'm going to install that and see if that brings my VS in line.
Jun 25, 2007 at 10:58 PM
I have VS 2005 SDK installed, I'll give the macro a shot later to see if I get any different information.
Jun 25, 2007 at 11:07 PM
Installing the SDK make no difference, unfortunately. Looks like i got a jacked VS install then
Jun 25, 2007 at 11:30 PM
bclubb,

Thanks, let me know how it turns out.

Arne,

I didn't excpect the SDK to help the original issue. Its purpose for DocProject is only that it provides the Help 2.x compiler, which is required by Interop.MSHelpCompiler. But thanks for trying anyway :)

The macro error sounds like you're just using the wrong value for the name variable. If that doesn't work then you can use the following if the test project is the only project in the solution:

Public Sub TestGlobals()
  Dim project As Project = DTE.ActiveSolutionProjects(0)
  project.Globals.VariableValue("Test") = "a value"
  project.Globals.VariablePersists("Test") = True
  project.Save()
End Sub

Thanks,
Dave
Jun 25, 2007 at 11:45 PM
BTW, I updated the code for this issue so that ArgumentNullException will be thrown by DocProject in the next release instead of NullReferenceException being thrown in .NET Framework code. I know that doesn't help you now but I thought you might like to know :)
Jun 26, 2007 at 1:31 AM
Edited Jun 26, 2007 at 1:50 AM
Got it... Apparently the name should have been projectname\projectname.csproj. At least that's how the solution had it stored rather than with the solution name. And that worked just fine.

Anyway, I think i found the real error. I.e. when i went through the wizard, i always went for the VS Orcas doc style not the MSDN 2005 style. So i tried that one and now all it good. I hope that wasn't a RTFM thing I overlooked that the VS Orcas style wasn't valid.

Having built the docs, I am not further unsure whether it's not working properly or this is the expected result. I.e. after the build i get an Html folder with a number of html files named with GUIDs. I can't find a proper entry point or a TOC. Is this what is supposed to happen with a base install? If so, how can I get to full doc w/ TOC generation and files named after the namespace qualified types? Am I missing templates?
Jun 26, 2007 at 2:14 AM
Hi Arne,

Thanks for the reply.


Anyway, I think i found the real error. I.e. when i went through the wizard, i always went for the VS Orcas doc style not the MSDN 2005 style. So i tried that one and now all it good. I hope that wasn't a RTFM thing I overlooked that the VS Orcas style wasn't valid.

I'm glad to here that you were able to build the documentation but I'm concerned now that you had a problem choosing the VS Orcas style, which should have worked fine too.

I wonder if bclubb was choosing VS Orcas and had the same problem as you, although bclubb did say "I...just choose the defaults" and VS 2005 is actually the default.


Having built the docs, I am not further unsure whether it's not working properly or this is the expected result. I.e. after the build i get an Html folder with a number of html files named with GUIDs.

Guid files names are the default, but you can change your project's settings in the Tools > Options > DocProject > Active Projects page.


I can't find a proper entry point or a TOC. Is this what is supposed to happen with a base install?

What kind of TOC do you want? If you use Show All Files you'll find the toc.xml file under buildhelp, which is DocProject's working directory. But that's normally considered to be a working file, not build output.

BTW, Sandcastle used to generate a root TOC node called Namespaces, but as of the latest release a root node is no longer generated. I mentioned this in the Sandcastle forums and I think they may add the ability to generate the Namespaces topic again in a subsequent release, but I don't know for sure.


If so, how can I get to full doc w/ TOC generation and files named after the namespace qualified types? Am I missing templates?


Enable this setting: Tools > Options > DocProject > Active Projects > Use friendly HTML file names.

To generate a TOC you need to enable compiled help generation for your project. You probably want to enable Produce Help 1.x in your project's settings.

Alternatively, you could have instead chosen Help 1.x in the New Project Wizard when you first created the DocProject.

Please read the How To... articles for more information.

Thanks,
Dave
Jun 26, 2007 at 3:15 AM
I was using VS Orcas, sorry about the confusion. I had tried it once like that and after that the wizard remembers your old choices. So I thought that maybe since I wasn't changing the drop down that may have had an effect. I'll try 2005 when I get back to work tomorrow.
Jun 26, 2007 at 6:53 AM
Hi bclubb,

Thanks for the response.

Do you think that the wizard shouldn't remember your choice of presentation?

I'm really stumped though as to how choosing the VS Orcas style could have the effect that it seems to have had on both of your systems.

For one thing, if an exception occurred it should have been logged to the Application event log and you should have seen a message box appear after clicking OK, making the error unavoidable. But if there is no error than I really don't know at this point how the code that saves your choice of presentation, and every other setting that you've chosen in the wizard, would not be saved the same way as if you had chosen any other presentation style. The particular presentation style that you choose doesn't change the save process at all and again, if there was an exception you should know about it.

Please let me know what you find out tomorrow.

Thanks,
Dave
Jun 26, 2007 at 6:55 AM
Thanks for the info. The last time I had to generate docs for my project was still under 1.1 and I used NDoc, which generated the HTML with an accompanying Namespace TOC frame. Since i'm now under 2.0, I decided to switch to SandCastle and I'm still getting used to the differences. I guess to get the behavior I'm after, I need to create a DocSiteProject instead.
Jun 26, 2007 at 7:11 AM
Hi Arne,

A DocSite will not produce a Namespaces node either. I just never updated the wiki images, if that's what you're going by.

I was actually surprised when I tested the June 2007 CTP of Sandcastle and discovered that it no longer generates a root topic out-of-the-box. If the next release of Sandcastle provides a switch to generate a Namespaces node than you'll have the option in DocProjects and DocSites. And in anticipation of that I decided not to update all of the wikis and images since Sandcastle was supposed to be released at the end of last week. Maybe it's time for me to update the wikis for the June CTP - but I think I'll give Sandcastle another week since I don't want to have to reverse all the changes back again either :)

Also, I'm working on a way to create custom topics so you'll also have control over the root node when I finish that feature for a future release.

Thanks,
Dave
Jun 26, 2007 at 7:41 AM
Hi,

The June 2007 CTP Refresh was released and I didn't even know it. The release page doesn't say anything about it being the Refresh and there was never any mention that it was actually released, as far as I know.

Anyway, I downloaded it and it appears that, as was suggested on Sandcastle's blog, the vsorcas style was renamed to hana, so that's why it's not working for you.

I'm currently working on updating the 1.6.2 release of DocProject, which should be available shortly.

Thanks to both of you for helping me try to figure out this issue.
Jun 26, 2007 at 11:16 AM
1.6.2 Release Candidate is now available.

If you still have any problems creating a new DocProject please let me know.

Thanks,
Dave
Jun 26, 2007 at 4:52 PM
Dave,

I assume The Orcas/Hana style is not supposed to show up in the wizard?

Aside from that, I had to install 1.6.2 twice. The first time, I started VS and it had problems with the add-in, so i re-ran the installer and now the Add-in loads again.

However both DocProject and DocSite error out with:

The "C:\Program Files\Visual Studio 2005 SDK\2007.02\VisualStudioIntegration\Tools\Sandcastle\\ProductionTools\XslTransform" process failed with exit code: 1.

As a separate follow-up to my previous off-topic... Maybe i'm using the wrong language, but DocSite (before i installed 1.6.2) does generate a namespace table of contents sidebar, which is the thing I've been after, so that people can actually navigate the entirety of the documentation.
Jun 26, 2007 at 5:49 PM
I just upgraded and everything works now. I uninstalled DocProject and Sandcastle then installed the new refresh of sandcastle and then the update of DocProject. Now I don't have any errors. Thanks for the quick responses Dave.
Jun 26, 2007 at 7:57 PM
bclubb,
Glad to hear it. Thanks for letting me know.

Arne,


I assume The Orcas/Hana style is not supposed to show up in the wizard?

Hana should show up now in place of VS Orcas. It's the same thing though.


Aside from that, I had to install 1.6.2 twice. The first time, I started VS and it had problems with the add-in, so i re-ran the installer and now the Add-in loads again.

I don't know why you had to install it twice. When you say that the add-in had problems, was there any error information? There will most likely be an entry in the Application event log. I'd like to see that if you don't mind.


The "C:\Program Files\Visual Studio 2005 SDK\2007.02\VisualStudioIntegration\Tools\Sandcastle\\ProductionTools\XslTransform" process failed with exit code: 1.

The error indicates that the XslTranform utility failed, but it doesn't indicate why. There should be a more detailed explanation in the build output window. Could you please post that here?


As a separate follow-up to my previous off-topic... Maybe i'm using the wrong language, but DocSite (before i installed 1.6.2) does generate a namespace table of contents sidebar, which is the thing I've been after, so that people can actually navigate the entirety of the documentation.

I see. Well, what you were after was a graphical user interface, not just an xml TOC or raw HTML files. You will also get something similar if you use compiled help 1.x.

Thanks,
Dave

Jun 26, 2007 at 11:38 PM
Uninstalled it all, rebooted, reinstalled, rebooted and now all is fine. Hana is there all builds without complaints. I'm using the DocSite option and that looks like the best way to go for me. Here's what NDoc static HTML looked like:

http://www.claassen.net/geek/lfs/doc/

I.e. it provided a TOC as a static html frame. Admitedly DocSite is a nicer interface, but it does mean i have to move the docs from apache to Win2k3/IIS
Jun 27, 2007 at 1:07 AM
Hi Arne,

Thanks for the update. I'm glad that you got it working.

- Dave