use PublishWebSite instead of Web Deployment Project?

Topics: Conceptual Topics, Features, General Discussion, General Questions
Apr 14, 2010 at 7:53 PM

DocProject Owner --

Please help.

Can one use use PublishWebSite instead of Web Deployment Project?

That is, at this link...

http://docproject.codeplex.com/wikipage?title=How%20To%20Build%20Help%20For%20a%20Web%20Site%20Project&referringTitle=Documentation

...we have the following...

"Build the Web Deployment Project to produce managed assemblies and optional XML documentation files that your DocProject or DocSite  can reference"

...and I am wondering if one cannot simply use VisualStudio's functionality for >Build, >PublishWebSite, to do, in effect, more-or-less the same thing?

(I am just a bit curious because PublishWebSite is built-in and and easy and GEFN for a lot of things where precompiling is necessary, IMHO.)

What do you think?

Please advise.

Thank you.

-- Mark Kamoski

Coordinator
Apr 14, 2010 at 10:14 PM

Hi Mark,

Sure, that will be fine as long as it produces an assembly and (optionally) an XML documentation file.  You'll need to add them as external sources in your DocProject or DocSite.

- Dave

Apr 15, 2010 at 11:30 AM

Dave --

 

(1).

Regarding this...

>>> that will be fine as long as it produces an assembly

...by "an assembly" do you mean "exactly one assembly"?

I ask because the built-in precompilation in VisualStudio usually generates more than one assembly, unless one employs a custom process to merge the assemblies .

I am wondering, in short, if DocProject+Sandcastle can run against a set of assemblies (for example the output VisualStudio's built-in pre-compilation), where it is not just a single assembly.

What do you think?

 

(2).

Regading this...

>>> (optionally) an XML documentation file

...I thought the XML documentation was generated wholly from the source-code XML comments and, as such, an XML documentation file ever been needed.

What is meant by "XML documentation file" here?

 

Please advise.

Thank you.

-- Mark Kamoski

Coordinator
Apr 15, 2010 at 3:52 PM

Hi Mark,

1. You can add multiple assemblies as external sources.  Or you can add an entire directory with a wildcard that tells DocProject to recurse into subdirectories as well.  I haven't tried compiling documentation against the multiple assembly output of a web site, so I can't say for sure that it will work.

This is one reason that I recommend using a Web Deployment Project (WDP) - it compiles everything into a single assembly and drops it into the bin folder.

2. The code compiler does not include your comments in the assembly.  Instead, it produces an XML documentation file along with the assembly.  In order for Sandcastle to know about your comments, you must tell it about this XML documentation file.  The External Sources dialog, available via the DocProject Properties window, has two columns: one for assemblies and one for XML documentation files.  The XML documentation column also supports directories and wildcards.

Sandcastle Help  § XML Documentation
http://docproject.codeplex.com/wikipage?title=Sandcastle%20Help#xmldoc

This is another reason that I recommend using a WDP.  I believe, although I'm not sure, that it will create a single XML documentation file for the assembly that is produced for your web site project.

WDP also has other advantages; e.g., it's an MSBuild file, which allows you to easily modify the build process of your web site.

- Dave

Apr 16, 2010 at 12:53 PM

Dave --

I guess the other alternative to using a Web Deployment Project (WDP) is to convert each Web Site Project to Web Application Project, right?

I think that is the plan that I will use, given that it seems like it would be quicker.

What do you think?

Please advise.

Thank you.

-- Mark Kamoski

 

 

Coordinator
Apr 16, 2010 at 4:11 PM

Hi Mark,

Yes.  I usually recommend Web Application projects instead of Web Sites.  They're better for several reasons, one of which is that they're easier to document.

However, I still use WDPs for all of my Web Application projects.  It simplifies deployment and provides a nice MSBuild hook for performing custom tasks on a build server.

- Dave