Sandcastle Visual Studio Project 10

Final update

Sorry, I’m not able to figure out what’s wrong with this, and since Frank has a better solution for Visual Studio integration, I’m cancelling this attempt. If you’re interested in the source code, send me an email! I think it’s better if I focus my efforts on the MSBuild script instead.

Update 3

Have a look at Frank Kroondijk’s Sandcastle plugin. It seems to work much better (at least looking at the video – I haven’t installed it yet).

Update 2

It seems there is still a bug of some sort that gives you an error message when creating a project. I’d recommend that you hold off on installing this until I can find a solution.

Update

There was a file missing in the msi-package, so you’ll have to uninstall the old version and repeat steps 2 and 3 below in order for it to work properly.

As I hinted in yesterdays post, I’ve been working on a Visual Studio plugin for the Sandcastle MSBuild-script, and today I’m happy enough with it to share it with the community. Be warned though, this is my first attempt at a VS project plugin, and it is most likely rather unstable so please realize the risks of installing it (worst-case scenario, you’ll have a broken Visual Studio).. That said, it works ok for me and uninstalling it seems to be fine too.

Installation instructions:

  1. Prerequisites: Visual Studio 2005 (Standard edition or better) and an unmodified version of Sandcastle.
  2. You’ll need the latest version (updated a few minutes ago) of the Sandcastle MSBuild-script.
  3. Download and install the SandcastleProjectSetup.msi-package.
  4. Open up a Visual Studio 2005 Command Prompt (you’ll find it on the Start menu under your Visual Studio Tools-folder) and run the following command:
    devenv.exe /setup

Usage:

After installing the package, a new Project type is available from the New/Add project dialog. Typically, you’ll add this project to an existing solution.

In order to bring up the main settings page, you simpy right-click the newly added project and select Properties. This is where you select which assemblies and documentation files you wish to include. You can include files from the current solution by clicking the Select button, or external files by clicking the Add button.

Finally, to actually build your documentation file, right click the project and select “Build”. The documentation will (if everything works as planned) end up in the a subfolder to the documentation project called Output.

If you get an error from the build engine, the best way to find out what’s wrong is to run the build outside of Visual Studio. You do that simply by running MSBuild on the [ProjectName].sandproj file. The most common error is probably an Unresolved Assembly Reference. Currently, you can only add dependencies manually to the .sandproj file. You’ll have to unload the project to do so.

Comments are always appreciated! If you’re interested in the (not-so-pretty) source code for this, why not send me an email! You’ll need the Visual Studio SDK (April 2006) installed for it to compile though. The address is: andlju (at) gmail (dot) com.

10 thoughts on “Sandcastle Visual Studio Project

  1. carey dot hackett at malvern dot co dot uk Aug 3,2006 16:08

    I have done everything you say to do on your blog to get this working, and I am not able to see "Documentation Project" under "SandcastleProject" in the "New Project" dialog.

    VS2005 on XP SP2 with all critical updates as of today.

    Have you heard this from anyone else?

    carey dot hackett at malvern dot co dot uk

  2. Anders Ljusberg Aug 3,2006 17:00

    Hehe, you are likely the first one to try it.. I will have to look into this tomorrow as I do not have the source code at hand now.. I had this happening to me too at first, but it was solved by running devenv.exe with the setup switch.

  3. Ken Aug 3,2006 20:58

    I have the same problem as Carey. It looks like the the msi installs fine but the add-in .dll is not copied to the hard drive. If it matters, my VS 2005 is not installed in the default location.

  4. Anders Ljusberg Aug 4,2006 07:04

    It appears the msi didn’t include all the necessary files. I’ll have a new version in an hour or so.

  5. Anders Ljusberg Aug 4,2006 07:21

    OK, try it again!
    You'll have to uninstall the version you have now, and then install the latest one. Oh, and don't forget to run devenv.exe /setup again!

    BTW, I can't tell you how much I *hate* building msi-packages… 🙂

  6. Conrad Agramont Aug 4,2006 07:26

    I gave it a shot. I was able to see the new project type to add, but I got the following error…

    Value cannot be null.
    Parameter name: type

    Conrad Agramont

  7. carey dot hackett at malvern dot co dot uk Aug 4,2006 08:13

    It’s me again. I did as you suggested, and I have the same error as Conrad.

  8. Anders Ljusberg Aug 4,2006 08:39

    I've reproduced the error but I'm afraid I have no idea what causes it. Could be that it only works with Visual Studio SDK installed or something like that (which would indicate that I've forgot yet another file in the MSI).

    Unfortunately, I'll have very little time working with this the next couple of days. Until then, I'd recommend you to simply use the MSBuild script by itself.

  9. Klaus Kuehne Dec 1,2006 08:14

    Unfortunately i couldn’t find the download?
    Ist it still available?

  10. anders Dec 1,2006 20:05

    Sorry Klaus, but no it isn’t available anymore. I canceled this project since there are many better solutions out there (see the link to Franks site above).

Comments are closed.