| 1 | <html>
|
|---|
| 2 | <head>
|
|---|
| 3 | <title>.NET Tasks</title>
|
|---|
| 4 | <link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css">
|
|---|
| 5 | </head>
|
|---|
| 6 |
|
|---|
| 7 | <h1>.NET tasks</h1>
|
|---|
| 8 | <h2>Introduction</h2>
|
|---|
| 9 |
|
|---|
| 10 |
|
|---|
| 11 | Ant support for .NET goes back to before .NET was released, and
|
|---|
| 12 | continues to be expanded based on user demand. Users writing nothing but
|
|---|
| 13 | a .NET application, may want to look at the .NET-based
|
|---|
| 14 | <A href="http://nant.sourceforge.net/">NAnt</A> project, that supports
|
|---|
| 15 | both the Microsoft and the Ximian managed <A
|
|---|
| 16 | href="http://go-mono.com/">Mono</A> project's implementation of the
|
|---|
| 17 | .NET framework.
|
|---|
| 18 | <p>
|
|---|
| 19 |
|
|---|
| 20 | Over time, the .NET tasks in Ant have tended to evolve to meet a few
|
|---|
| 21 | limited needs. Firstly, developers working with complex deployment problems may
|
|---|
| 22 | want to use ant to use the fairly advanced deployment tasks Ant ships
|
|---|
| 23 | with. Secondly, anyone who has a cross-platform project can use these
|
|---|
| 24 | tasks to cover the .NET side of the problem. Here, cross-platform can
|
|---|
| 25 | mean more than just Java and .NET: the C++ tasks in the ant-contrib
|
|---|
| 26 | project on sourceforge can be used with Ant to do native C++ and .NET
|
|---|
| 27 | cross development if that is your need. Finally, Ant support for .NET
|
|---|
| 28 | lets one automate .NET development under an automated build process,
|
|---|
| 29 | such as AntHill or Cruise Control.
|
|---|
| 30 |
|
|---|
| 31 | <p>
|
|---|
| 32 |
|
|---|
| 33 | What this means is that the Ant tasks for .NET support do not get as
|
|---|
| 34 | much rigorous use as the Java tools, and are evolving more slowly -that
|
|---|
| 35 | includes the time for support calls to change. But as a consequence,
|
|---|
| 36 | developers working on .NET support have more freedom to play around with
|
|---|
| 37 | the code. It also means that the fairly unusual set of tasks supported
|
|---|
| 38 | by ant enable a few interesting operations that can not be performed any
|
|---|
| 39 | other way:
|
|---|
| 40 | <ol>
|
|---|
| 41 |
|
|---|
| 42 | <li>Integrating with a Java based SOAP Service -generating C# code from
|
|---|
| 43 | the server's WSDL and running it against the server.
|
|---|
| 44 | </li>
|
|---|
| 45 | <li>Building and deploying a C#-based Web Service, then using the Apache
|
|---|
| 46 | Axis tasks to create JUnit tests to call the endpoints.
|
|---|
| 47 |
|
|---|
| 48 | <li>Patching .NET type libraries to work with more complex IDL than the
|
|---|
| 49 | basic <code><importtypelib></code> wrapper around tlbimport supports. Hence the
|
|---|
| 50 | disassembler and the reassembler.
|
|---|
| 51 | </li>
|
|---|
| 52 |
|
|---|
| 53 | </ol>
|
|---|
| 54 | Needless to say, possible does not mean easy.
|
|---|
| 55 | <A href="http://www.manning.com/hatcher/chap15.pdf">Chapter 15</A> of
|
|---|
| 56 | Java Development with Ant covers the first of these, using the Ant1.5
|
|---|
| 57 | version of the tasks. Going the other way -generating Java client
|
|---|
| 58 | code and JUnit testcases is covered in
|
|---|
| 59 | <A href="http://www.iseran.com/Steve/papers/interop/">The Wondrous curse
|
|---|
| 60 | of Interop</A>. The final trick, IDL and Typelib abuse, is not
|
|---|
| 61 | documented as we do not want to encourage such an ugly practice. It,
|
|---|
| 62 | can, however, be done if absolutely necessary. The trick is a sequence
|
|---|
| 63 | of <importtypelib/>, <ildasm>, <replace> and finally
|
|---|
| 64 | <ilasm>.
|
|---|
| 65 |
|
|---|
| 66 | <h3>Task List</h3>
|
|---|
| 67 |
|
|---|
| 68 | <table border="0" >
|
|---|
| 69 | <tr>
|
|---|
| 70 | <td><a href="csc.html">Csc</a></td>
|
|---|
| 71 | <td>Compiles C# code</td>
|
|---|
| 72 | </tr>
|
|---|
| 73 |
|
|---|
| 74 | <tr>
|
|---|
| 75 | <td><a href="vbc.html">vbc</a></td>
|
|---|
| 76 | <td>Compiles VB.NET code</td>
|
|---|
| 77 | </tr>
|
|---|
| 78 |
|
|---|
| 79 | <tr>
|
|---|
| 80 | <td><a href="jsharpc.html">jsharpc</a></td>
|
|---|
| 81 | <td>Compiles J# files</td>
|
|---|
| 82 | </tr>
|
|---|
| 83 |
|
|---|
| 84 | <tr>
|
|---|
| 85 | <td><a href="ildasm.html">ildasm</a></td>
|
|---|
| 86 | <td>Disassembles .NET executables and libraries</td>
|
|---|
| 87 | </tr>
|
|---|
| 88 |
|
|---|
| 89 | <tr>
|
|---|
| 90 | <td><a href="ilasm.html">ilasm</a></td>
|
|---|
| 91 | <td>Assembles .il files</td>
|
|---|
| 92 | </tr>
|
|---|
| 93 |
|
|---|
| 94 | <tr>
|
|---|
| 95 | <td><a href="wsdltodotnet.html">WsdlToDotnet</a></td>
|
|---|
| 96 | <td>Generates .NET code (C# or VB) from a WSDL file</td>
|
|---|
| 97 | </tr>
|
|---|
| 98 |
|
|---|
| 99 | <tr>
|
|---|
| 100 | <td><a href="importtypelib.html">ImportTypelib</a></td>
|
|---|
| 101 | <td>Imports a COM type library into .NET</td>
|
|---|
| 102 | </tr>
|
|---|
| 103 |
|
|---|
| 104 | </table>
|
|---|
| 105 |
|
|---|
| 106 | <hr>
|
|---|
| 107 | <h3>Common .NET Datatypes </h3>
|
|---|
| 108 |
|
|---|
| 109 | There are some datatypes that are common to the core compiler classes:
|
|---|
| 110 | csc, vbc and jsharpc
|
|---|
| 111 |
|
|---|
| 112 | <h4>Resource</h4>
|
|---|
| 113 |
|
|---|
| 114 | This is a resource that is included in the build. Ant uses this for
|
|---|
| 115 | dependency checking -if resources included this way have changed, the
|
|---|
| 116 | executable or library will be rebuilt.
|
|---|
| 117 | <p>
|
|---|
| 118 | <table border="1" cellpadding="2" cellspacing="0">
|
|---|
| 119 | <tr>
|
|---|
| 120 | <td valign="top"><b>Attribute</b></td>
|
|---|
| 121 | <td valign="top"><b>Description</b></td>
|
|---|
| 122 | <td align="center" valign="top"><b>Required</b></td>
|
|---|
| 123 | </tr>
|
|---|
| 124 | <tr>
|
|---|
| 125 | <td valign="top">File</td>
|
|---|
| 126 | <td valign="top">the resource to include</td>
|
|---|
| 127 | <td align="center" valign="top">Yes</td>
|
|---|
| 128 | </tr>
|
|---|
| 129 | <tr>
|
|---|
| 130 | <td valign="top">name</td>
|
|---|
| 131 | <td valign="top">the name of the resource.
|
|---|
| 132 | Optional unless the resource is
|
|---|
| 133 | marked as public or private</td>
|
|---|
| 134 | <td align="center" valign="top">No</td>
|
|---|
| 135 | </tr>
|
|---|
| 136 | <tr>
|
|---|
| 137 | <td valign="top">embed</td>
|
|---|
| 138 | <td valign="top">flag to control whether the resource
|
|---|
| 139 | is embedded in the assembly, or just linked to it</td>
|
|---|
| 140 | <td align="center" valign="top">No -default is true</td>
|
|---|
| 141 | </tr>
|
|---|
| 142 | <tr>
|
|---|
| 143 | <td valign="top">public</td>
|
|---|
| 144 | <td valign="top">VB only: flag to control if a resource should be
|
|---|
| 145 | public or private. Set to true for public, false for private
|
|---|
| 146 | and leave undefined for for neither. </td>
|
|---|
| 147 | <td align="center" valign="top">No</td>
|
|---|
| 148 | </tr>
|
|---|
| 149 | </table>
|
|---|
| 150 |
|
|---|
| 151 | <h5>Examples</h5>
|
|---|
| 152 |
|
|---|
| 153 | <pre>
|
|---|
| 154 | <resource file="app.ico" name="icon"/>
|
|---|
| 155 | <resource file="splash.jpg"/>
|
|---|
| 156 | <resource name="splash" file="splash.jpg" public="false"/>
|
|---|
| 157 | </pre>
|
|---|
| 158 |
|
|---|
| 159 | <h4>Define</h4>
|
|---|
| 160 |
|
|---|
| 161 | This is a definition; in .NET these can either be defined or undefined,
|
|---|
| 162 | unlike C++ #defines, which can be either undefined or arbitrary text.
|
|---|
| 163 | The Ant compilation tasks can unconditionally add definitions, or
|
|---|
| 164 | conditionally set a compile-time definition if an ant property is
|
|---|
| 165 | defined or not.
|
|---|
| 166 | <p>
|
|---|
| 167 |
|
|---|
| 168 | Dependency Logic: the tasks are not (yet) clever enough to remember what
|
|---|
| 169 | the last definitions were and trigger a rebuild when they change. Clean
|
|---|
| 170 | build the code when the defines are likely to be different.
|
|---|
| 171 | <p>
|
|---|
| 172 | <table border="1" cellpadding="2" cellspacing="0">
|
|---|
| 173 | <tr>
|
|---|
| 174 | <td valign="top"><b>Attribute</b></td>
|
|---|
| 175 | <td valign="top"><b>Description</b></td>
|
|---|
| 176 | <td align="center" valign="top"><b>Required</b></td>
|
|---|
| 177 | </tr>
|
|---|
| 178 | <tr>
|
|---|
| 179 | <td valign="top">name</td>
|
|---|
| 180 | <td valign="top">the name of the definition</td>
|
|---|
| 181 | <td align="center" valign="top">Yes</td>
|
|---|
| 182 | </tr>
|
|---|
| 183 | <tr>
|
|---|
| 184 | <td valign="top">if</td>
|
|---|
| 185 | <td valign="top">name of a ant property to test for;
|
|---|
| 186 | the definition is only set if this property is defined.</td>
|
|---|
| 187 | <td align="center" valign="top">No</td>
|
|---|
| 188 | </tr>
|
|---|
| 189 | <tr>
|
|---|
| 190 | <td valign="top">unless</td>
|
|---|
| 191 | <td valign="top">name of a ant property to test for;
|
|---|
| 192 | the definition is only set if this property is undefined.</td>
|
|---|
| 193 | <td align="center" valign="top">No</td>
|
|---|
| 194 | </tr>
|
|---|
| 195 | </table>
|
|---|
| 196 |
|
|---|
| 197 | <h5>Examples</h5>
|
|---|
| 198 |
|
|---|
| 199 | <pre>
|
|---|
| 200 | <define name="unsafe"/>
|
|---|
| 201 | <define name="debug" if="build.debug"/>
|
|---|
| 202 | <define name="dotnet" unless="build.mono"/>
|
|---|
| 203 | </pre>
|
|---|
| 204 |
|
|---|
| 205 | <hr>
|
|---|
| 206 | <h3> Change Log </h3>
|
|---|
| 207 |
|
|---|
| 208 | <h4>Ant1.6</h4>
|
|---|
| 209 | This revision goes along with NET 1.1, though there is no reason why
|
|---|
| 210 | it should not work on other versions.
|
|---|
| 211 | <p>
|
|---|
| 212 |
|
|---|
| 213 | <ol>
|
|---|
| 214 | <li>vbc task</li>
|
|---|
| 215 | <li>jsharpc task</li>
|
|---|
| 216 | <li>mono support</li>
|
|---|
| 217 | <li>ilasm</li>
|
|---|
| 218 | <li>tlbimport</li>
|
|---|
| 219 | <li>Reference filesets in the compiler tasks</li>
|
|---|
| 220 | <li>definitions in the compiler tasks</li>
|
|---|
| 221 | <li>multiple source filesets in the compiler tasks. If these are used, the
|
|---|
| 222 | implicit fileset is disabled</li>
|
|---|
| 223 | </ol>
|
|---|
| 224 |
|
|---|
| 225 | The compile tasks: vbc, jsharpc, and csc, all contain lots of common code
|
|---|
| 226 | in a shared base class: if you can use one you should be able to use
|
|---|
| 227 | another.
|
|---|
| 228 |
|
|---|
| 229 | <h4>Ant 1.5</h4>
|
|---|
| 230 | This revision goes along with NET 1.0 (SP1)
|
|---|
| 231 | <ol>
|
|---|
| 232 | <li>CSC: added filealign</li>
|
|---|
| 233 | <li>CSC: added reference to office.dll</li>
|
|---|
| 234 | <li>CSC: dependency checking! only if destFile is set!
|
|---|
| 235 | <li>WsdlToDotnet written
|
|---|
| 236 | </ol>
|
|---|
| 237 |
|
|---|
| 238 | <h4>Version 0.5</h4>
|
|---|
| 239 | This revision goes along with NET 1.0 (SP1)
|
|---|
| 240 | <ol>
|
|---|
| 241 | <li>CSC: added filealign</li>
|
|---|
| 242 | <li>CSC: added reference to office.dll</li>
|
|---|
| 243 | <li>CSC: dependency checking! only if destFile is set!
|
|---|
| 244 | <li>WsdlToDotnet written
|
|---|
| 245 | </ol>
|
|---|
| 246 |
|
|---|
| 247 | <h4>Version 0.4</h4>
|
|---|
| 248 | This is the beta-2 revision of the tasks.
|
|---|
| 249 | <ol>
|
|---|
| 250 | <li>ILASM: pulled the owner attribute, added keyfile for giving binaries a strong name
|
|---|
| 251 | (MD5 hash of the checksum)</li>
|
|---|
| 252 | <li>CSC: added win32res , noConfig, utf8output, fullpaths</li>
|
|---|
| 253 | <li>CSC: </li>
|
|---|
| 254 | </ol>
|
|---|
| 255 |
|
|---|
| 256 | <h4>Version 0.3</h4>
|
|---|
| 257 |
|
|---|
| 258 | The changes here reflect Beta-1 of the dotnet SDK and experience of use in
|
|---|
| 259 | more complex projects. This build does not work with the older SDK,
|
|---|
| 260 | primarily because the automatic reference feature references libraries
|
|---|
| 261 | only found in the new SDK version.
|
|---|
| 262 | <p>
|
|---|
| 263 | External changes</p>
|
|---|
| 264 | <ul>
|
|---|
| 265 | <li>Recursive inclusion of .cs and .il files</li>
|
|---|
| 266 |
|
|---|
| 267 | <li>Documentation enhanced, includes examples and details of all parameters</li>
|
|---|
| 268 |
|
|---|
| 269 | <li>The csc task automatically includes the common dotnet assemblies, so
|
|---|
| 270 | there is no need to remember to refer to 'System.dll', 'System.Web.Services',
|
|---|
| 271 | etc. This feature can be disabled by setting the 'includeDefaultReferences'
|
|---|
| 272 | flag to false. </li>
|
|---|
| 273 |
|
|---|
| 274 | <li> References can also be referred to using the ReferenceFiles parameter, which
|
|---|
| 275 | is an ant path specification. The old 'references' string is still retained.</li>
|
|---|
| 276 | <li> An 'extraoptions' attribute enables the build file to include any CSC options
|
|---|
| 277 | which are not explicitly supported in the CSC task. </li>
|
|---|
| 278 | </ul>
|
|---|
| 279 |
|
|---|
| 280 | Internal changes
|
|---|
| 281 | <ul>
|
|---|
| 282 | <li>Some minor refactoring (move common code a method)</li>
|
|---|
| 283 | <li>Application of Jedits JavaStyle task resulted in a major reshaping of
|
|---|
| 284 | the codebase and the insertion of a blank line every second line. Significant
|
|---|
| 285 | effort was required to revert some (but not all) changes.</li>
|
|---|
| 286 | <li>Removed throws clause from methods which can't throw exception
|
|---|
| 287 | </ul>
|
|---|
| 288 |
|
|---|
| 289 | The test harness has been expanded to include unicode source file
|
|---|
| 290 | (the build works but the rest of the system has 'issues' with high unicode
|
|---|
| 291 | package and method names)
|
|---|
| 292 |
|
|---|
| 293 | <h4>Version 0.2</h4>
|
|---|
| 294 | First public edition, added to the ant cvs tree. Tested on the PDC build of
|
|---|
| 295 | the dotnet SDK only, and still immature. The command execution code was
|
|---|
| 296 | refactored out into a 'NetCommand' class for re-use. The Ilasm task was added
|
|---|
| 297 | at this time.
|
|---|
| 298 |
|
|---|
| 299 | <h4>Version 0.1</h4>
|
|---|
| 300 | Initial proof of concept; very rudimentary support for CSC only.
|
|---|
| 301 |
|
|---|
| 302 | <p align="center">Copyright © 2000-2004 The Apache Software Foundation. All rights
|
|---|
| 303 | Reserved.</p>
|
|---|
| 304 |
|
|---|
| 305 | </body>
|
|---|
| 306 | </html>
|
|---|
