Getting Started with .Net
MPXJ uses a tool called IKVM to convert the original Java version of MPXJ into .Net assemblies. The MPXJ .Net assemblies provided via NuGet and shipped as part of the MPXJ distribution use a "legacy" version of IKVM to do this. The "modern" version of IKVM allows .Net assemblies to be generated in a different, and ultimately more future-proof way. However there are, at present, some minor disadvantages to using the approach based on the "modern" version of IKVM. These disadvantages are being addressed, and ultimately assemblies produced by the "modern" version of IKVM will become the default way to include MPXJ in your project.
MPXJ assemblies (legacy IKVM)
For many people the easiest way to work with MPXJ is to use the assemblies generated by the "legacy" version of IKVM. This are available via NuGet and also as part of the zip file distribution from GitHub or SourceForge.
MPXJ ships with a set of .Net Framework and .Net Core assemblies, which are
managed for you by NuGet or can be found in the src.net\lib\net45
and
src.net\lib\netcoreapp3.1
folders of the distribution respectively.
There are actually three different .Net DLLs available for MPXJ - you only need one of these:
- mpxj.dll - this is the default .Net version, the API is identical to the Java version
- mpxj-for-csharp.dll - in this version the API has been modified to make it less like Java and more like C#: there are properties rather than getter and setter methods and the method names follow the same uppercase initial letter convention used by C#.
- mpxj-for-vb.dll - this version also transforms getters and setters into properties, but the method names are unchanged. VB is case insensitive and can't cope with the seeing two methods whose name differs only by case
As noted above, in the "for C#" and "for VB" versions of the MPXJ DLL, getters and setters have been replaced by properties. For example, where you would have previously written code like this:
String text = task.getText();
task.setText(text);
Now when you work with the "for C#" and "for VB" versions of the MPXJ DLL, you'll be able to write code in a more familiar style:
String text = task.Text
task.Text = text;
Also noted above, in the case of the "for C#" MPXJ DLL, method names have been modified to begin with an initial capital, so the code will again have a more familiar style. For example, using the original Java method names you'd write something like this:
Task task = projectFile.addTask();
Using the "for C#" DLL your code will look like this:
Task task = projectFile.AddTask();
Once you have selected the version of the MPXJ DLL most suitable for your
project, you will need to add its dependencies. If you are using NuGet to
manage your dependencies, this is done for you automatically. If you are
managing the dependencies manually, the files you need will all be in the
relevant sub folder with the src.net\lib
folder of the MPXJ distribution.
MPXJ assemblies (modern IKVM)
The modern version of IKVM provides an extension to modern SDK-style .Net projects which allows you to refer to a Java library using Maven (probably the most common dependency management solution for Java projects). This means that your .Net project will be working directly with the original Java version of the library, which will automatically be translated into .Net assemblies for you as you build your project.
Note that this build process can be time-consuming when your project is first built using this approach, but the results of this translation will be reused, so subsequent builds will be more rapid. You may also see various transient warning messages as this first build completes. These can be ignored and will disappear once your project has finished building.
To include MPXJ in your project using the modern version of IKVM, edit your project file and include the following lines:
<ItemGroup>
<PackageReference Include="IKVM.Maven.Sdk" Version="1.6.9" />
</ItemGroup>
<ItemGroup>
<MavenReference Include="net.sf.mpxj:mpxj" Version="12.9.2"/>
</ItemGroup>
The first <ItemGroup>
you are adding enables IKVM's Maven integration
functionality. The second <ItemGroup>
simply refers to the version of MPXJ
you'd like to use from Maven.
The advantages of using MPXJ this way are:
- Improved performance when compared to the version of MPXJ generated by legacy IKVM.
- Supports modern .Net platforms and architectures, not all of which will be supported by legacy IKVM.
- Works more efficiently with the Visual Studio debugger.
- Benefits from ongoing bug fixes and enhancements in IKVM.
The disadvantages of using MPXJ this way are:
- There is no translation of getters and setters into .Net properties.
- All method names remain as "Java-style" initial lower case.
As mentioned earlier, work is underway to provide address these disadvantages by providing a "wrapper" assembly which hides the "Java-ness" of the original MPXJ library.
.Net samples
MPXJ ships with some sample files which can be found in the src.net\samples
folder of the distribution. These files illustrate how the MPXJ API can be
used to manipulate project data. In particular the MpxjQuery
example
shows how various elements which make up the project data can be queried.
Two versions of this utility are present in src.net\samples
, one written in C#,
and the other written in Visual Basic (VB) to illustrate the basics of using
MPXJ in either language. Even if you are developing software in a .Net
language you may still find it useful to refer to the Java examples, and
indeed the original Java source of MPXJ, to give you an insight into how the
API can be used. There is also a standalone repository containing sample .Net
code for MPXJ covering use of the library in more depth. This repository
can be found here.
.Net and Java types
The .Net version of MPXJ has been generated directly from the Java version using
a tool called IKVM. One of the side effects of using IKVM to perform this
conversion is that the MPXJ exposes .Net versions of the original Java data
types, so for example you will find that the API returns a type called
LocalDateTime
rather than a .Net DateTime
, and collections which don't
expose the familiar IEnumerable
interface.
To simplify the translation between Java and .Net types, a set of extension
methods have been provided. These are included n the NuGet package, and the
source can be found in the src.net\utilities
folder, in a project called
MpxjUtilities
. This project contains extension methods which enhance both
Java and .Net classes to make it easier to pass data to and from the API. For
example the extension method ToIEnumerable
is added to Java collection data
types which allows them to be iterated using the familiar foreach
.Net
syntax.
To use these extension methods, simply add a reference to the MpxjUtilities
assembly in your own project. The methods themselves are documented in the
source, and examples of their use can be seen in the samples provided in the
src.net\samples
folder.
MPXJ and the GAC
For your convenience two batch files are provided in the src.net\lib\net45
directory: mpxj-gac-install.bat
and mpxj-gac-uninstall.bat
. These batch
files install the MPXJ assemblies into the GAC and uninstall the MPXJ
assemblies from the GAC using the
gacutil
global
assembly cache tool. Note that these batch files assume that gacutil
is
available on the path.