FileDocCategorySizeDatePackage
Ildasm.javaAPI DocApache Ant 1.7014509Wed Dec 13 06:16:18 GMT 2006org.apache.tools.ant.taskdefs.optional.dotnet

Ildasm

public class Ildasm extends org.apache.tools.ant.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.

ant.task
category="dotnet"

Fields Summary
private static final org.apache.tools.ant.util.FileUtils
FILE_UTILS
private File
sourceFile
source file (mandatory)
private File
destFile
dest file (mandatory)
private boolean
progressBar
progress bar switch
private String
encoding
what is our encoding
private boolean
bytes
/bytes flag for byte markup
private boolean
linenumbers
line numbers? /linenum
private boolean
rawExceptionHandling
/raweh flag for raw exception handling
private boolean
showSource
show the source; /source
private boolean
quoteallnames
/quoteallnames to quote all names
private boolean
header
/header for header information
private boolean
assembler
when false, sets the /noil attribute to suppress assembly info
private boolean
metadata
include metadata /tokens
private String
visibility
what visibility do we want.
private String
item
specific item to disassemble
private String
executable
override for the executable
private File
resourceDir
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
Constructors Summary
Methods Summary
public voidexecute()
do the work

throws
BuildException if there is an error.

        log("This task is deprecated and will be removed in a future version\n"
            + "of Ant.  It is now part of the .NET Antlib:\n"
            + "http://ant.apache.org/antlibs/dotnet/index.html",
            Project.MSG_WARN);
        validate();
        if (!isDisassemblyNeeded()) {
            return;
        }
        NetCommand command = new NetCommand(this, "ildasm", executable);
        command.setFailOnError(true);
        //fill in args
        command.addArgument("/text");
        command.addArgument("/out=" + destFile.toString());
        if (!progressBar) {
            command.addArgument("/nobar");
        }
        if (linenumbers) {
            command.addArgument("/linenum");
        }
        if (showSource) {
            command.addArgument("/source");
        }
        if (quoteallnames) {
            command.addArgument("/quoteallnames");
        }
        if (header) {
            command.addArgument("/header");
        }
        if (!assembler) {
            command.addArgument("/noil");
        }
        if (metadata) {
            command.addArgument("/tokens");
        }
        command.addArgument("/item:", item);
        if (rawExceptionHandling) {
            command.addArgument("/raweh");
        }
        command.addArgument(EncodingTypes.getEncodingOption(encoding));
        if (bytes) {
            command.addArgument("/bytes");
        }
        command.addArgument("/vis:", visibility);

        //add the source file
        command.addArgument(sourceFile.getAbsolutePath());

        //determine directory: resourceDir if set,
        //the dir of the destFile if not
        File execDir = resourceDir;
        if (execDir == null) {
            execDir = destFile.getParentFile();
        }
        command.setDirectory(execDir);

        //now run
        try {
            command.runCommand();
        } catch (BuildException e) {
            //forcibly delete the output file in case of trouble
            if (destFile.exists()) {
                log("Deleting destination file as it may be corrupt");
                destFile.delete();
            }
            //then rethrow the exception
            throw e;
        }
private booleanisDisassemblyNeeded()
Test for disassembly being needed; use existence and granularity correct date stamps

return
true iff a rebuild is required.

        if (!destFile.exists()) {
            log("Destination file does not exist: a build is required",
                    Project.MSG_VERBOSE);
            return true;
        }
        long sourceTime = sourceFile.lastModified();
        long destTime = destFile.lastModified();
        if (sourceTime > (destTime + FILE_UTILS.getFileTimestampGranularity())) {
            log("Source file is newer than the dest file: a rebuild is required",
                    Project.MSG_VERBOSE);
            return true;
        } else {
            log("The .il file is up to date", Project.MSG_VERBOSE);
            return false;
        }
public voidsetAssembler(boolean assembler)
enable (default) or disable assembly language in the output

param
assembler a boolean value.

        this.assembler = assembler;
public voidsetBytes(boolean bytes)
enable or disable (default) the original bytes as comments

param
bytes a boolean value.

        this.bytes = bytes;
public voidsetDestFile(java.io.File destFile)
the output file (required)

param
destFile the destination file.

        this.destFile = destFile;
public voidsetEncoding(org.apache.tools.ant.taskdefs.optional.dotnet.Ildasm$EncodingTypes encoding)
Select the output encoding: ascii, utf8 or unicode

param
encoding the enumerated value.

        this.encoding = encoding.getValue();
public voidsetExecutable(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.

param
executable the name of the executable to use.

        this.executable = executable;
public voidsetHeader(boolean header)
include header information; default false.

param
header a boolean value.

        this.header = header;
public voidsetItem(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))

param
item the item to decode.

        this.item = item;
public voidsetLinenumbers(boolean linenumbers)
include line number information; default=false

param
linenumbers a boolean value.

        this.linenumbers = linenumbers;
public voidsetMetadata(boolean metadata)
include metadata information

param
metadata a boolean value.

        this.metadata = metadata;
public voidsetProgressBar(boolean progressBar)
show a graphical progress bar in a window during the process; off by default

param
progressBar a boolean value.

        this.progressBar = progressBar;
public voidsetQuoteallnames(boolean quoteallnames)
quote all names.

param
quoteallnames a boolean value.

        this.quoteallnames = quoteallnames;
public voidsetRawExceptionHandling(boolean rawExceptionHandling)
enable raw exception handling (default = false)

param
rawExceptionHandling a boolean value.

        this.rawExceptionHandling = rawExceptionHandling;
public voidsetResourceDir(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

param
resourceDir the directory in which to create resources.



                                                     
        
        this.resourceDir = resourceDir;
public voidsetShowSource(boolean showSource)
include the source as comments (default=false)

param
showSource a boolean value.

        this.showSource = showSource;
public voidsetSourceFile(java.io.File sourceFile)
the file to disassemble -required

param
sourceFile the file to disassemble.

        this.sourceFile = sourceFile;
public voidsetSrcFile(java.io.File sourceFile)
alternate name for sourceFile

param
sourceFile the source file.

        setSourceFile(sourceFile);
public voidsetVisibility(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#;

param
visibility the options to use.

        this.visibility = visibility;
private voidvalidate()
verify that source and dest are ok

        if (sourceFile == null || !sourceFile.exists() || !sourceFile.isFile()) {
            throw new BuildException("invalid source");
        }
        if (destFile == null || destFile.isDirectory()) {
            throw new BuildException("invalid dest");
        }
        if (resourceDir != null
                && (!resourceDir.exists() || !resourceDir.isDirectory())) {
            throw new BuildException("invalid resource directory");
        }