Sandcastle and ASP.NET

[=?Utf-8?B?TWFyY0c=?=]

Is there a relatively straightforward way to get Sandcastle hooked into the
asp.net 2.0 development process? I have a C# app I'm developing that has code
in both the root and App_Code directories.

Sorry for the post here - only confilicting info in the various blogs.

Thanks,
Marc

[Steven Cheng[MSFT]]

Hi Marc,

From your description, you're wondering the proper way to integrate the
Sandcastle into ASP.NET project compilation so as to generate document for
it, correct?

Based on my research, Sandcastle will accept .net assembly or xml build
document file as input to generate target help document. Thus, for ASP.NET
2.0 web application, since it is by default dynamically compiled, you need
to perform precompilation so as to generate assemblies. And use the
precompiled output assemblies as input for Sandcastle to generate output
document. For precompilation, you can consider use Web Deployment Project:

#Visual Studio 2005 Web Deployment Projects
http://msdn2.microsoft.com/en-us/asp.net/aa336619.aspx

Or you can consider using the Web application project(built-in support
after install vs 2005 sp1), this project can help build vs 2003/asp.net 1.1
like web site project that has pregenerated assemblies in "bin" dir, you
can use them to generate help document:

#Visual Studio 2005 Web Application Projects
http://msdn2.microsoft.com/en-us/asp.net/aa336618.aspx

Here is a msdn forum thread discussing on the same topic:
#Sand Castle with ASP.NET 2.0 Applications
http://forums.microsoft.com/MSDN/Sho...07177&SiteID=1

Hope this helps.

Sincerely,

Steven Cheng

Microsoft MSDN Online Support Lead

==================================================

Get notification to my posts through email? Please refer to
http://msdn.microsoft.com/subscripti...ult.aspx#notif
ications.

Note: The MSDN Managed Newsgroup support offering is for non-urgent issues
where an initial response from the community or a Microsoft Support
Engineer within 1 business day is acceptable. Please note that each follow
up response may take approximately 2 business days as the support
professional working with you may need further investigation to reach the
most efficient resolution. The offering is not appropriate for situations
that require urgent, real-time or phone-based interactions or complex
project analysis and dump analysis issues. Issues of this nature are best
handled working with a dedicated Microsoft Support Engineer by contacting
Microsoft Customer Support Services (CSS) at
http://msdn.microsoft.com/subscripti...t/default.aspx.

==================================================

This posting is provided "AS IS" with no warranties, and confers no rights.

[Thomas Hansen]

On Mar 28, 6:55 am, [e-mail] (Steven Cheng[MSFT])
wrote:

Hi Marc,

From your description, you're wondering the proper way to integrate the
Sandcastle into ASP.NET project compilation so as to generate document for
it, correct?

DON'T use Sandcastle...!!
It £$%&@ BIG time!!
Use the Alpha version of NDoc for .Net 2.0 (which can be found with a
little bit of pain googling around)
..t

--
http://ajaxwidgets.com
ASP.NET 2.0 Ajax Widgets

[=?Utf-8?B?TWFyY0c=?=]

Steven,

Sorry - still in trouble...

First, asp.net does not have project properties, so, unlike a windows app,
there's no properties section and no "build" page where you would normally
check the "doc" option and specify a doc dIRECTORY.

I did find a page talking about web apps, and added the following to my
web.config

<system.codedom>
<compilers>
<compiler language="c#;cs;csharp" extension=".cs"
type="Microsoft.CSharp.CSharpCodeProvider, System,
Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
compilerOptions="/doc:C:\xyz\XMLdocs\out.xml"/>
</compilers>
</system.codedom>
Note that the doc option ends with a file name - you cannot quit at the
directory level.

When I went and did a "rebuild solution" the xml file contained information
about the last (alphabetically latest) .cs file, so I assume that the same
file was repeatedly reused during the compilation. After that, I went back
and modified a couple of .cs's and did a standard build and the file was
replaced with partial information about the files I changed.

For non web apps, you just check of the DOC option and specify a directory.
Each .cs winds up with its own .xml documentation file, which is of cours
what you need/want.

Also, in the xml file I see

<assembly>
<name>App_Web_btqkavbn</name>
</assembly>

I know that I'm going to have to publish the site in order to get a dll, but
will it actually create a dll with that weird name?

thx
Marc

[=?Utf-8?B?TWFyY0c=?=]

Thomas,

Have you had any success using it with ASP.NET projects??

Marc

[Steven Cheng[MSFT]]

Hi Marc,

If you're doing to do the precompilation first and generate document, you
can consider using Web Deployment project:

#Visual Studio 2005 Web Deployment Projects
http://msdn2.microsoft.com/en-us/asp.net/aa336619.aspx

it can help customize the precompilation, such as specify the output
assembly's name.

In addition, if you can use the "Web application project"(like VS
2003/asp.net 1.1 project model), it also provide the "xml document" setting
in project's property dialog settings. And the assemblies are generated(in
private bin dir) when you build the project.

Sincerely,

Steven Cheng

Microsoft MSDN Online Support Lead
This posting is provided "AS IS" with no warranties, and confers no rights.

[=?Utf-8?B?TWFyY0c=?=]

Steven,

I must be pretty dense, because this can't be that hard...

The web deployment project does not offer anything re: xml documentation in
the properties sheets. The MSBuild file does however have a MergeXmlDocs
property but this assumes that aspnet_compiler has produced these. This is
what I'm trying to get to happen.

The Web Deployment project has some nice features, but I don't think I need
any of them.

As to a Web Application project, when I start a VS2005 and attempt to creat
a new project and select "Web Application Project" I get an error box
saying...

>The project file c:\documents and settings\....\Temqsdfa.21x\WbApp.csproj cannot be opened

The project type is not supported by this installation.

In any case, to go back to the original problem, all I'm trying to do is to
get aspnet_compiler to produce the xml files with the comments in them from
my .cs files. As noted earlier, my attempts to do this in the web.config by
specifying compilerOptions="/doc:..." fails because it only produces one
output file and that is for the last .cs compiled.

I simply need to tell the &^%$ compiler to create an xml file for each .cs
that it compiles in the course of a build.

Marc

[Steven Cheng[MSFT]]

Thanks for your reply Joe,

yes, web deployment project doesn't provide "xml document file ..."
setting. Therefore, you need to use assembly as direct input for Sandcastle
to generate document.

For Web Application Project, are you installing it through Visual Studio
2005 SP1 or install it separately? It seems the project template file is
corrupted. You can try look at the problem file(the template in the cache
location) and try clean it or copy a correct one from other place to see
whether it works. So far, I think this project type would be the most
elegant one for your case.

Sincerely,

Steven Cheng

Microsoft MSDN Online Support Lead
This posting is provided "AS IS" with no warranties, and confers no rights.

[=?Utf-8?B?TWFyY0c=?=]

Steven,

>>Therefore, you need to use assembly as direct input for Sandcastle
to generate document

Are you saying that Sandcastle can do the whole job from the assemblies
themselves WITHOUT geting the COMMENTS.XML file extracted from the .cs files
by the compiler?? I don't think that that is the case.

I did manage to get the Web Application project template working, and as you
said, it does provide a "Generate XML" option in the property sheets.
Unfortunately, I am at the end of my development phase and have a completed
and functional Web Site project in place. The WebApp project is good for new
projects or upgrading VS2003 projects - not converting from VS2005 Web Site
projects.

I made a quick attempt of copying my files to a new WebApp project and
including them in the project. The build attempt failed, complaining about
missing connection strings coming from my datasets (XSDs). I suspect that
this is just the beginning of a series of things that would have to be fixed.
In any case, I don't want to risk porting a debugged, functioning app to a
different project type.

Its hard enough to make a living in this business without having to fight
with your tools.

Marc

[Steven Cheng[MSFT]]

Thanks for your reply Marc,

For the input of Sandcastle, I'll contact some Sandcastle project specific
engineers to confirm this.

For web applicaiton Project, yes, you can not simply copy all the content
of web site project into it because they have different page
development/compile model. Web application projecct is like VS
2003/ASP.NET1.X project.

Anyway, I'll update you if I get any new information on this.

Sincerely,

Steven Cheng

Microsoft MSDN Online Support Lead
This posting is provided "AS IS" with no warranties, and confers no rights.