stevel 02/04/11 00:28:12
Modified: docs/manual/OptionalTasks dotnet.html
Log:
documentation of new task + cleanup of the rest
Revision Changes Path
1.8 +166 -196 jakarta-ant/docs/manual/OptionalTasks/dotnet.html
Index: dotnet.html
===================================================================
RCS file: /home/cvs/jakarta-ant/docs/manual/OptionalTasks/dotnet.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- dotnet.html 10 Apr 2002 00:38:40 -0000 1.7
+++ dotnet.html 11 Apr 2002 07:28:12 -0000 1.8
@@ -3,188 +3,19 @@
<title>.NET Tasks</title>
</head>
-<body bgcolor="#ffffff">
-<h1>.NET classes for Ant</h1>
+<body>
+<h1>.NET tasks</h1>
-<h2>Vision</h2>
-<p>
-Make ant the definitive build tool for .NET projects, just
-as it is becoming for java projects
-</p>
-
-<h2>Detail</h2>
-
-<p>
-The emergent policy in big java projects is 'IDE for code and debug';
-Ant for builds, test and deployment. While IDEs are great for an
-individual development task, Ant not only rebuilds everything insanely
-fast, it has great support for modern deployment tasks -ftp upload,
-EJB servers, SQL commands, all can be done from a relatively simple
-XML declaration of what you want done. Also in a large project
-(especially open source) there is no means of dictating which IDE to use.
-Ant gives IDE independence, cross platform portability and ease of
-extensibility. </p>
-
-<p>
-
-Projects using .net should be able to use the same tool. This will
-avoid everyone being dependent on Visual Studio.net (if they have it)
-supplemented with makefiles and batch files. Anyone doing mixed java/dotnet
-development will be particulary grateful, as they can have a unified build
-process. </p>
-
-<p>
-
-If at sometime in the future bits of .net do appear on different platforms
-then ant based build files will migrate -once the ant tasks have been
-migrated and any hard codings of DOS-descendant file system conventions
-removed from the build.xml files.</p>
-
-<h2>Key .net Tasks</h2>
-
-<ol>
-<li>csc - csharp compiler - *.csc -> output</li>
-<li>ilasm - IL assembler - *.il ->.exe or .dll</li>
-<li>ResX - ResXToResources.exe .resx -> .resources</li>
-<li>al - assembly linker (.dll) -></li>
-<li>Signcode - .exe + keys -> .exe</li>
-<li>Resgen - .properties -> .resources</li>
-<li>Type Library Exporter (TlbExp.exe) .dll -> .tlb</li>
-<li>TlbImp.exe Type Library Importer </li>
-<li>RegAsm.exe Assembly Registration Tool .dll -> .reg | registration</li>
-</ol>
-
-<h2>Ant Wrapper for net tasks</h2>
-
-Rarely used .net command line tools can be invoked manually. The key tasks
-to address are the common steps in a build process and those which benefit
-from the file pattern matching function.
-
-<p>
-
-The esoteric tasks can then supported on demand by those who need them.
-The initial .net tasks should provide a foundation for that demand creation
-to be simple. </p>
-
-<h2>Plan</h2>
-
-<ol>
-
-<li>code up C sharp task and distribute for feedback & identify possible
-aid</li>
-<li>Use for a real end to end development task</li>
-<li>Add the next task I need (whatever that is)</li>
-<li>Refactor to produce a base class for .net tasks</li>
-<li>Leave it other people write all the other tasks</li>
-</ol>
-
-<h2>Risks</h2>
-<ul>
-<li>
-The .net SDK is unstable; the next builds will change the commands,
arguments
-and behaviours. Probability: 100%. Impact: 2 days.</li>
-<li>Portable tasks turn out to be harder than envisaged
- (=reworking if/when non Win32 .net build tools appear)</li>
-
-</ul>
-
-<hr>
-<h2>Using Ant in .net projects</h2>
-
-To use the net tasks one needs
-<ul>
-
-<li> A Windows box (or any other platform which supports the .net build
tools)</li>
-
-<li> JavaVM - Java1.1 or later; Java1.3 recommended.</li>
-
-<li> Ant downloaded and the environment and path variables set up so
-that typing 'ant' invokes ant via a batch file.</li>
-
-<li> An XML parser for ant. The usual distributions include an appropriate
-version crimson.jar and jaxp.jar.</li>
-
-<li> the .net tasks archive (dotnettasks.jar) included in the
- ant\lib directory</li>
-
-<li> The .net sdk installed with the binaries on the path. (Test: type
CSC)</li>
-
-<li> A build.xml file to describe the build process</li>
-</ul>
-
-<hr>
-<h2> Change Log </h2>
-
-<h4>Version 0.5</h4>
-This revision goes along with NET 1.0 (SP1)
-<ol>
-<li>CSC: added filealign</li>
-<li>CSC: added reference to office.dll</li>
-</ol>
-
-<h4>Version 0.4</h4>
-This is the beta-2 revision of the tasks.
-<ol>
-<li>ILASM: pulled the owner attribute, added keyfile for giving binaries a
strong name
-(MD5 hash of the checksum)</li>
-<li>CSC: added win32res , noConfig, utf8output, fullpaths</li>
-<li>CSC: </li>
-</ol>
-
-<h4>Version 0.3</h4>
-The changes here reflect Beta-1 of the dotnet SDK and experience of use in
-more complex projects. This build does not work with the older SDK,
-primarily because the automatic reference feature references libraries
-only found in the new SDK version.
-<p>
-External changes</p>
-<ul>
-<li>Recursive inclusion of .cs and .il files</li>
-
-<li>Documentation enhanced, includes examples and details of all
parameters</li>
-
-<li>The csc task automatically includes the common dotnet assemblies, so
-there is no need to remember to refer to 'System.dll', 'System.Web.Services',
- etc. This feature can be disabled by setting the 'includeDefaultReferences'
- flag to false. </li>
-
- <li> References can also be referred to using the ReferenceFiles parameter,
which
-is an ant path specification. The old 'references' string is still
retained.</li>
-<li> An 'extraoptions' attribute enables the build file to include any CSC
options
-which are not explicitly supported in the CSC task. </li>
-</ul>
-
-Internal changes
-<ul>
-<li>Some minor refactoring (move common code a method)</li>
-<li>Application of Jedits JavaStyle task resulted in a major reshaping of
-the codebase and the insertion of a blank line every second line. Significant
-effort was required to revert some (but not all) changes.</li>
-<li>Removed throws clause from methods which can't throw exceptions </li>
-</ul>
-
-The test harness has been expanded to include unicode source file
-(the build works but the rest of the system has 'issues' with high unicode
-package and method names)
-
-<h4>Version 0.2</h4>
-First public edition, added to the ant cvs tree. Tested on the PDC build of
-the dotnet SDK only, and still immature. The command execution code was
-refactored out into a 'NetCommand' class for re-use. The Ilasm task was added
-at this time.
-
-<h4>Version 0.1</h4>
-Initial proof of concept; very rudimentary support for CSC only.
<hr>
-<h2>Task: CSC</h2>
+<h2><CSC></h2>
This task compiles CSharp source into executables or modules.
-This task compiles CSharp source into executables or modules.
-The task will only work on win2K until other platforms support csc.exe or
-an equivalent. CSC.exe must be on the execute path too.
+This task compiles CSharp source into executables or modules. The task will
+only work on win2K/XP or other platforms with csc.exe or an equivalent.
+CSC must be on the execute path.
<p>
All parameters are optional: <csc/> should suffice to produce a debug
@@ -193,13 +24,16 @@
<p>
-The task is a directory based task, so attributes like
<b>includes="**/*.cs"</b> and
-<b>excludes="broken.cs"</b> can be used to control the files
pulled in. By default,
+The task is a directory based task, so attributes like
+<b>includes="**/*.cs"</b> and
+<b>excludes="broken.cs"</b> can be used to control
+the files pulled in. By default,
all *.cs files from the project folder down are included in the command.
-When this happens the output file -if not specified-
+When this happens the destFile -if not specified-
is taken as the first file in the list, which may be somewhat hard to
control.
-Specifying the output file with <b>'outfile'</b> seems prudent. </p>
-
+Specifying the output file with <b>'destfile'</b> seems prudent. </p>
+<p>
+Also, dependency checking only works if destfile is set.
<table border="1" cellpadding="2" cellspacing="0">
<tr>
@@ -226,10 +60,15 @@
<tr>
<td valign="top">debug</td>
<td valign="top">include debug information</td>
- <td valign="top">"true"(default) or "false"</td>
+ <td valign="top">"true"(default)</td>
</tr>
<tr>
+ <td valign="top">destFile</td>
+ <td valign="top">name of exe/library to create</td>
+ <td valign="top">"example.exe"</td>
+ </tr>
+<tr>
<td valign="top">docFile</td>
<td valign="top">name of file for documentation</td>
<td valign="top">"doc.xml"</td>
@@ -314,11 +153,6 @@
<td valign="top">"true" or "false"(default)</td>
</tr>
<tr>
- <td valign="top">outputFile</td>
- <td valign="top">filename of output</td>
- <td valign="top">"example.exe"</td>
- </tr>
-<tr>
<td valign="top">references</td>
<td valign="top">Semicolon separated list of dlls to refer to</td>
<td valign="top">"mylib.dll;nunit.dll"</td>
@@ -383,11 +217,11 @@
definitions="RELEASE"
excludes="src/unicode_class.cs"
mainClass = "MainApp"
- outputFile="NetApp.exe"
+ destFile="NetApp.exe"
/>
</pre>
<hr>
-<h2> Task: ilasm </h2>
+<h2><ilasm></h2>
<p>Task to assemble .net 'Intermediate Language' files.
The task will only work on windows until other platforms support csc.exe or
an equivalent. ilasm.exe must be on the execute path too.
@@ -429,7 +263,7 @@
<td valign="top">debug</td>
<td valign="top">include debug information</td>
<td valign="top">true (default)</td>
- </tr>
+ </tr>
<tr>
<td valign="top">excludes</td>
@@ -449,16 +283,16 @@
<td></td>
</tr>
-<tr>
- <td valign="top">failOnError</td>
- <td valign="top">Should a failed compile halt the build?</td>
- <td valign="top">"true"(default)</td>
- </tr>
-<tr>
+ <tr>
+ <td valign="top">failOnError</td>
+ <td valign="top">Should a failed compile halt the build?</td>
+ <td valign="top">"true"(default)</td>
+ </tr>
+ <tr>
<td valign="top">fullpaths</td>
<td valign="top">Should error text provide the full path to files</td>
<td valign="top">"true"(default)</td>
- </tr>
+ </tr>
<tr>
<td valign="top">includes</td>
<td valign="top">comma separated list of patterns of files that must be
@@ -517,7 +351,143 @@
owner="secret"
/>
</pre>
+<h2><WsdlToDotnet></h2>
+Why add a wrapper to the MS WSDL tool?
+So that you can verify that your web services, be they written with Axis or
+anyone else's SOAP toolkit, work with .NET clients.
+<p>
+This task is dependency aware when using a file as a source and destination;
+so if you <get> the file (with <code>usetimestamp="true"</code>) then
+you only rebuild stuff when the WSDL file is changed. Of course,
+if the server generates a new timestamp every time you ask for the WSDL,
+this is not enough...use the <filesmatch> <condition> to
+to byte for byte comparison against a cached WSDL file then make
+the target conditional on that test failing.
+
+<table border="1" cellpadding="2" cellspacing="0">
+ <tr>
+ <td valign="top"><b>Attribute</b></td>
+ <td valign="top"><b>Description</b></td>
+ <td align="center" valign="top"><b>Example</b></td>
+ </tr>
+ <tr>
+ <td valign="top">destFile</td>
+ <td valign="top">name of file to generate. Required</td>
+ <td valign="top">ApacheNet.cs</td>
+ </tr>
+ <tr>
+ <td valign="top">srcFile</td>
+ <td valign="top">name of WSDL file to use.
+ Required if url is not set</td>
+ <td valign="top">service.wsdl</td>
+ </tr>
+ <tr>
+ <td valign="top">url</td>
+ <td valign="top">url to retrive WSDL from.
+ required if srcFile is unset</td>
+ <td valign="top">http://localhost/service?wsdl</td>
+ </tr>
+ <tr>
+ <td valign="top">server</td>
+ <td valign="top">generate server stubs, not client proxy code.
+ optional; default false</td>
+ <td valign="top">"false"(default)</td>
+ </tr>
+ <tr>
+ <td valign="top">namespace</td>
+ <td valign="top">namespace to place the source in.
+ optional; default ""</td>
+ <td valign="top">Apache.Net</td>
+ </tr>
+ <tr>
+ <td valign="top">language</td>
+ <td valign="top">language; one of "CS", "JS", or "VB"
+ optional; </td>
+ <td valign="top"> "CS" (default)</td>
+ </tr>
+ <tr>
+ <td valign="top">failOnError</td>
+ <td valign="top">Should failure halt the build?</td>
+ <td valign="top">"true"(default)</td>
+ </tr>
+ <tr>
+ <td valign="top">extraOptions</td>
+ <td valign="top">Any extra options which aren't explicitly
+ supported by the task, like all the proxy server config stuff</td>
+ <td></td>
+ </tr>
+
+ </table>
+<hr>
+
<hr>
+<h2> Change Log </h2>
+
+<h4>Version 0.5</h4>
+This revision goes along with NET 1.0 (SP1)
+<ol>
+<li>CSC: added filealign</li>
+<li>CSC: added reference to office.dll</li>
+<li>CSC: dependency checking! only if destFile is set!
+<li>WsdlToDotnet written
+</ol>
+
+<h4>Version 0.4</h4>
+This is the beta-2 revision of the tasks.
+<ol>
+<li>ILASM: pulled the owner attribute, added keyfile for giving binaries a
strong name
+(MD5 hash of the checksum)</li>
+<li>CSC: added win32res , noConfig, utf8output, fullpaths</li>
+<li>CSC: </li>
+</ol>
+
+<h4>Version 0.3</h4>
+
+The changes here reflect Beta-1 of the dotnet SDK and experience of use in
+more complex projects. This build does not work with the older SDK,
+primarily because the automatic reference feature references libraries
+only found in the new SDK version.
+<p>
+External changes</p>
+<ul>
+<li>Recursive inclusion of .cs and .il files</li>
+
+<li>Documentation enhanced, includes examples and details of all
parameters</li>
+
+<li>The csc task automatically includes the common dotnet assemblies, so
+there is no need to remember to refer to 'System.dll', 'System.Web.Services',
+ etc. This feature can be disabled by setting the 'includeDefaultReferences'
+ flag to false. </li>
+
+ <li> References can also be referred to using the ReferenceFiles parameter,
which
+is an ant path specification. The old 'references' string is still
retained.</li>
+<li> An 'extraoptions' attribute enables the build file to include any CSC
options
+which are not explicitly supported in the CSC task. </li>
+</ul>
+
+Internal changes
+<ul>
+<li>Some minor refactoring (move common code a method)</li>
+<li>Application of Jedits JavaStyle task resulted in a major reshaping of
+the codebase and the insertion of a blank line every second line. Significant
+effort was required to revert some (but not all) changes.</li>
+<li>Removed throws clause from methods which can't throw exceptions </li>
+</ul>
+
+The test harness has been expanded to include unicode source file
+(the build works but the rest of the system has 'issues' with high unicode
+package and method names)
+
+<h4>Version 0.2</h4>
+First public edition, added to the ant cvs tree. Tested on the PDC build of
+the dotnet SDK only, and still immature. The command execution code was
+refactored out into a 'NetCommand' class for re-use. The Ilasm task was added
+at this time.
+
+<h4>Version 0.1</h4>
+Initial proof of concept; very rudimentary support for CSC only.
+
+
<p align="center">Copyright © 2000-2002 Apache Software Foundation. All
rights
Reserved.</p>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
