Adding Executable Info to Config Files

NMaven has a concept of two types of executables:

1. An executable plugin that exists in a predetermined place on the file system. These are typically executables that are part of the .NET framework or part of some other 3rd party program.
2. An executable plugin that is resolved from a Maven repo. The NMaven .NET plugins NMaven.Plugin.Resx and NMaven.Plugin.Settings fall into this category.

How you handle each case is slightly different. In the first case, where the executable is already installed on the file system, you add support for the executable by adding an entry in the executable-plugins.xml file. Take the example below where XSD is part of the .NET framework. The MS:XSD:SCHEMA entry uses a standard DefaultNetExecutable implementation. The executable tag denotes the command as it is executed from the commandline, in this case xsd. The commandFilter gives a list of command options that the plugin will accept from the invoking AbstractMojo implementation.

NMaven will look at the vendor and frameworkVersion to see if the xsd executable exists within the framework's install or SDK root for either Microsoft of Mono, depending on which vendor you are using to build. If the executable does exist in one of these locations, then it constructs the absolute path. In the xsd case, on windows NMaven may find the xsd file at: C:\Program Files\Microsoft.NET\SDK\v2.0\Bin or C:\Program Files\Mono-1.2.3.1\bin. If NMaven does not find the file, it will execute without a path (so in this case you will need to make sure that the executable exists within the system path).

Sample executable plugins entry:

 <executablePlugins>
  <executablePlugin>
    <identifier>MS:XSD:SCHEMA</identifier>
    <pluginClass>org.apache.maven.dotnet.executable.impl.DefaultNetExecutable</pluginClass>
    <vendor>MICROSOFT</vendor>
    <executable>xsd</executable>
    <profile>XSD:SCHEMA</profile>
    <frameworkVersions>
      <frameworkVersion>2.0.50727</frameworkVersion>
      <frameworkVersion>1.1.4322</frameworkVersion>
    </frameworkVersions>
    <platforms>
      <platform>
        <operatingSystem>Windows</operatingSystem>
      </platform>
    </platforms>
    <commandFilter>
      <includes>
        <include>classes</include>
        <include>dataset</include>
        <include>element</include>
        <include>fields</include>
        <include>enableDataBinding</include>
        <include>namespace</include>
        <include>language</include>
        <include>out</include>
        <include>o</include>
        <include>type</include>
        <include>uri</include>
        <include>parameters</include>
      </includes>
    </commandFilter>
  </executablePlugin>
  <executablePlugin>
    <identifier>MS:RESGEN</identifier>
    <pluginClass>org.apache.maven.dotnet.executable.impl.DefaultNetExecutable</pluginClass>
    <vendor>MICROSOFT</vendor>
    <executable>resgen</executable>
    <profile>RESGEN</profile>
    <frameworkVersions>
      <frameworkVersion>2.0.50727</frameworkVersion>
      <frameworkVersion>1.1.4322</frameworkVersion>
    </frameworkVersions>
    <platforms>
      <platform>
        <operatingSystem>Windows</operatingSystem>
      </platform>
    </platforms>
  </executablePlugin>
</executablePlugins>

Adding an executable plugin that exists in a predetermined place

To create an executable plugin that exists in a predetermined place, do the following:

1. From the root of your project directory, type:

    mvn archetype:create -DgroupId=<<myGroupid>>                               \
                         -DartifactId=<<myArtifactId>>                         \
                         -DarchetypeArtifactId=maven-archetype-netexecutable   \
                         -DarchetypeGroupId=org.apache.maven.dotnet            \
                         -DarchetypeVersion=0.14
   

2. Make sure to add an entry in the executable-plugins.xml file, located within the dotnet-core module. Replace each param: $vendor, $exe, .. with the appropriate values.

     <executablePlugin>
       <identifier>${ID}</identifier>
       <pluginClass>org.apache.maven.dotnet.executable.impl.DefaultNetExecutable</pluginClass>
       <vendor>${vendor}</vendor>
       <executable>${exe}</executable>
       <profile>${profile}</profile>
       <frameworkVersions>
         <frameworkVersion>2.0.50727</frameworkVersion>
         <frameworkVersion>1.1.4322</frameworkVersion>
       </frameworkVersions>
       <platforms>
         <platform>
           <operatingSystem>Windows</operatingSystem>
         </platform>
       </platforms>
     </executablePlugin>
   

3. Add profile ADD_PROFILE to the meta-data of the profile field of this class. This profile name should match the $profile within the executable-plugins.xml.
4. Add any special commands to the getCommands method.
5. Recompile the dotnet-core component.
6. Rename this class and install this Mojo component.

   public class NetExecutableMojo
       extends AbstractMojo
   {
       /**
        * @component
        */
       private org.apache.maven.dotnet.executable.NetExecutableFactory netExecutableFactory;
   
       /**
        * The maven project.
        *
        * @parameter expression="${project}"
        * @required
        */
       private MavenProject project;
   
       /**
        * The Vendor for the executable.
        *
        * @parameter expression="${vendor}"
        */
       private String vendor;
   
       /**
        * @parameter expression = "${frameworkVersion}"
        */
       private String frameworkVersion;
   
       /**
        * The profile that the executable should use.
        *
        * @parameter expression = "${profile}" default-value = "<<ADD_PROFILE>>"
        */
       private String profile;
   
       public void execute()
           throws MojoExecutionException
       {
           try
           {
               netExecutableFactory.getNetExecutableFor( vendor, frameworkVersion,
                   profile, getCommands(), null ).execute();
           }
           catch ( ExecutionException e )
           {
           ...
           }
           catch ( PlatformUnsupportedException e )
           {
           ...
           }
       }
   
       public List<String> getCommands()
           throws MojoExecutionException
       {
           List<String> commands = new ArrayList<String>();
           //<<ADD COMMANDS HERE>>
           return commands;
       }
   }
   

Creating an executable plugin that is resolved from a Maven repo

In the second case, where the executable is not already installed, you add an entry within the net-dependencies.xml file. This file tells NMaven how to resolve the executable from a Maven repository.

 <netDependencies>
    <netDependency>
        <groupId>NMaven.Utility.ResX</groupId>
        <artifactId>resx</artifactId>
        <versionId>0.14</versionId>
        <type>exe</type>
    </netDependency>
    <netDependency>
        <groupId>NMaven.Utility.Settings</groupId>
        <artifactId>SettingsGenerator</artifactId>
        <versionId>0.14</versionId>
       <type>exe</type>
   </netDependency>
</netDependencies>

Executing an executable from a Mojo

In the case where you have added the executable entry in the executable-plugins.xml file, you should use the NetExecutableFactory.getNetExecutableFor method within the Mojo's execute method.

  netExecutableFactory.getNetExecutableFor(vendor, frameworkVersion, profile,
    project, getCommands(), null).execute();

In the case where you have added the net dependency entry in the net-dependencies.xml file, you should use the NetExecutableFactory.getNetExecutableFromRepository method within the Mojo's execute method.

  netExecutableFactory.getNetExecutableFromRepository("NMaven.Plugin.ResX", "resx",
    vendorInfo, project, localRepository, commands).execute();