org.apache.tools.ant.taskdefs.optional.dotnet
Class Ildasm

java.lang.Object
  extended by org.apache.tools.ant.ProjectComponent
      extended by org.apache.tools.ant.Task
          extended by org.apache.tools.ant.taskdefs.optional.dotnet.Ildasm
All Implemented Interfaces:
java.lang.Cloneable

public class Ildasm
extends Task

Task to take a .NET or Mono -generated managed executable and turn it into ILASM assembly code. Useful when converting imported typelibs into assembler before patching and recompiling, as one has to do when doing advanced typelib work.

As well as generating the named output file, the ildasm program will also generate resource files Icons.resources Message.resources and a .res file whose filename stub is derived from the source in ways to obscure to determine. There is no way to control whether or not these files are created, or where they are created (they are created in the current directory; their names come from inside the executable and may be those used by the original developer). This task creates the resources in the directory specified by resourceDir if set, else in the same directory as the destFile.

This task requires the .NET SDK installed and ildasm on the path. To disassemble using alternate CLR systems, set the executable attribute to the name/path of the alternate implementation -one that must support all the classic ildasm commands.

Dependency logic: the task executes the command if the output file is missing or older than the source file. It does not take into account changes in the options of the task, or timestamp differences in resource files. When the underlying ildasm executable fails for some reason, it leaves the .il file in place with some error message. To prevent this from confusing the dependency logic, the file specified by the dest attribute is always deleted after an unsuccessful build.


Nested Class Summary
static class Ildasm.EncodingTypes
          encoding options; the default is ascii
static class Ildasm.VisibilityOptions
          visibility options for decoding
 
Field Summary
 
Fields inherited from class org.apache.tools.ant.Task
target, taskName, taskType, wrapper
 
Fields inherited from class org.apache.tools.ant.ProjectComponent
description, location, project
 
Constructor Summary
Ildasm()
           
 
Method Summary
 void execute()
          do the work
 void setAssembler(boolean assembler)
          enable (default) or disable assembly language in the output
 void setBytes(boolean bytes)
          enable or disable (default) the original bytes as comments
 void setDestFile(java.io.File destFile)
          the output file (required)
 void setEncoding(Ildasm.EncodingTypes encoding)
          Select the output encoding: ascii, utf8 or unicode
 void setExecutable(java.lang.String executable)
          override the name of the executable (normally ildasm) or set its full path.
 void setHeader(boolean header)
          include header information; default false.
 void setItem(java.lang.String item)
          name a single item to decode; a class or a method e.g item="Myclass::method" or item="namespace1::namespace2::Myclass:method(void(int32))
 void setLinenumbers(boolean linenumbers)
          include line number information; default=false
 void setMetadata(boolean metadata)
          include metadata information
 void setProgressBar(boolean progressBar)
          show a graphical progress bar in a window during the process; off by default
 void setQuoteallnames(boolean quoteallnames)
          quote all names.
 void setRawExceptionHandling(boolean rawExceptionHandling)
          enable raw exception handling (default = false)
 void setResourceDir(java.io.File resourceDir)
          Set the name of the directory for resources to be created.
 void setShowSource(boolean showSource)
          include the source as comments (default=false)
 void setSourceFile(java.io.File sourceFile)
          the file to disassemble -required
 void setSrcFile(java.io.File sourceFile)
          alternate name for sourceFile
 void setVisibility(java.lang.String visibility)
          This method sets the visibility options.
 
Methods inherited from class org.apache.tools.ant.Task
bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType
 
Methods inherited from class org.apache.tools.ant.ProjectComponent
clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Ildasm

public Ildasm()
Method Detail

setResourceDir

public void setResourceDir(java.io.File resourceDir)
Set the name of the directory for resources to be created. We cannot control their names, but we can say where they get created. If not set, the directory of the dest file is used

Parameters:
resourceDir - the directory in which to create resources.

setExecutable

public void setExecutable(java.lang.String executable)
override the name of the executable (normally ildasm) or set its full path. Do not set a relative path, as the ugly hacks needed to create resource files in the dest directory force us to change to this directory before running the application. i.e use <property location> to create an absolute path from a relative one before setting this value.

Parameters:
executable - the name of the executable to use.

setEncoding

public void setEncoding(Ildasm.EncodingTypes encoding)
Select the output encoding: ascii, utf8 or unicode

Parameters:
encoding - the enumerated value.

setAssembler

public void setAssembler(boolean assembler)
enable (default) or disable assembly language in the output

Parameters:
assembler - a boolean value.

setBytes

public void setBytes(boolean bytes)
enable or disable (default) the original bytes as comments

Parameters:
bytes - a boolean value.

setDestFile

public void setDestFile(java.io.File destFile)
the output file (required)

Parameters:
destFile - the destination file.

setHeader

public void setHeader(boolean header)
include header information; default false.

Parameters:
header - a boolean value.

setItem

public void setItem(java.lang.String item)
name a single item to decode; a class or a method e.g item="Myclass::method" or item="namespace1::namespace2::Myclass:method(void(int32))

Parameters:
item - the item to decode.

setLinenumbers

public void setLinenumbers(boolean linenumbers)
include line number information; default=false

Parameters:
linenumbers - a boolean value.

setMetadata

public void setMetadata(boolean metadata)
include metadata information

Parameters:
metadata - a boolean value.

setProgressBar

public void setProgressBar(boolean progressBar)
show a graphical progress bar in a window during the process; off by default

Parameters:
progressBar - a boolean value.

setQuoteallnames

public void setQuoteallnames(boolean quoteallnames)
quote all names.

Parameters:
quoteallnames - a boolean value.

setRawExceptionHandling

public void setRawExceptionHandling(boolean rawExceptionHandling)
enable raw exception handling (default = false)

Parameters:
rawExceptionHandling - a boolean value.

setShowSource

public void setShowSource(boolean showSource)
include the source as comments (default=false)

Parameters:
showSource - a boolean value.

setSourceFile

public void setSourceFile(java.io.File sourceFile)
the file to disassemble -required

Parameters:
sourceFile - the file to disassemble.

setSrcFile

public void setSrcFile(java.io.File sourceFile)
alternate name for sourceFile

Parameters:
sourceFile - the source file.

setVisibility

public void setVisibility(java.lang.String visibility)
This method sets the visibility options. It chooses one or more of the following, with + signs to concatenate them:
 pub : Public
 pri : Private
 fam : Family
 asm : Assembly
 faa : Family and Assembly
 foa : Family or Assembly
 psc : Private Scope
e.g. visibility="pub+pri". Family means protected in C#;

Parameters:
visibility - the options to use.

execute

public void execute()
             throws BuildException
do the work

Overrides:
execute in class Task
Throws:
BuildException - if there is an error.