16 SWIG and C#

The purpose of the C# module is to offer an automated way of accessing existing C/C++ code from .NET languages. The wrapper code implementation uses the Platform Invoke (PINVOKE) interface to access natively compiled C/C++ code. The PINVOKE interface has been chosen over Microsoft's Managed C++ interface as it is portable to both Microsoft Windows and non-Microsoft platforms. PINVOKE is part of the ECMA/ISO C# specification. Swig C# works equally well on non-Microsoft operating systems such as Linux, Solaris and Apple Mac using Mono and Portable.NET.

The C# module is very similar to the Java module, so until some documentation has been written, please use the Java documentation as a guide to using SWIG with C#. The rest of this chapter should be read in conjunction with the Java documentation as it lists the main differences.

Director support (virtual method callbacks into C#) has not yet been implemented and is the main missing feature compared to Java. Less of the STL is supported and there are also a few minor utility typemaps in the various.i library which are missing.

The most noteable differences to Java are the following:

• When invoking SWIG use the -csharp command line option instead of -java.
• The -package command line option does not exist.
• The -namespace <name> commandline option will generate all code into the namespace specified by <name>.
• The -dllimport <name> commandline option specifies the name of the DLL for the DllImport attribute for every PInvoke method. If this commandline option is not given, the DllImport DLL name is the same as the module name. This option is useful for when one wants to invoke SWIG multiple times on different modules, yet compile all the resulting code into a single DLL.
• C/C++ variables are wrapped with C# properties and not JavaBean style getters and setters.
• Global constants are generated into the module class. There is no constants interface.
• There is no implementation for type unsafe enums - not deemed necessary.
• The default enum wrapping approach is proper C# enums, not typesafe enums.
  Note that %csconst(0) will be ignored when wrapping C/C++ enums with proper C# enums. This is because C# enum items must be initialised from a compile time constant. If an enum item has an initialiser and the initialiser doesn't compile as C# code, then the %csconstvalue directive must be used as %csconst(0) will have no effect. If it was used, it would generate an illegal runtime initialisation via a PINVOKE call.
• C# doesn't support the notion of throws clauses. Therefore there is no 'throws' typemap attribute support for adding exception classes to a throws clause. Likewise there is no need for an equivalent to %javaexception.

• Typemap equivalent names:

  jni                         -> ctype
  jtype                       -> imtype
  jstype                      -> cstype
  javain                      -> csin
  javaout                     -> csout
  javainterfaces              -> csinterfaces and csinterfaces_derived
  javabase                    -> csbase
  javaclassmodifiers          -> csclassmodifiers
  javacode                    -> cscode
  javaimports                 -> csimports
  javabody                    -> csbody
  javafinalize                -> csfinalize
  javadestruct                -> csdestruct
  javadestruct_derived        -> csdestruct_derived
  

• Additional typemaps:

  csvarin                     C# code property set typemap
  csvarout                    C# code property get typemap
  

• Feature equivalent names:

  %javaconst                  -> %csconst
  %javaconstvalue             -> %csconstvalue
  %javamethodmodifiers        -> %csmethodmodifiers
  

• Pragma equivalent names:

  %pragma(java)               -> %pragma(csharp)
  jniclassbase                -> imclassbase
  jniclassclassmodifiers      -> imclassclassmodifiers
  jniclasscode                -> imclasscode
  jniclassimports             -> imclassimports
  jniclassinterfaces          -> imclassinterfaces
  

• Special variable equivalent names:

  $javaclassname              -> $csclassname
  $javainput                  -> $csinput
  $jnicall                    -> $imcall
  

$dllimport
This is a C# only special variable that can be used in typemaps, pragmas, features etc. The special variable will get translated into the value specified by the -dllimport commandline option if specified, otherwise it is equivalent to the $module special variable.

The intermediary classname has PINVOKE appended after the module name instead of JNI, for example modulenamePINVOKE.

The directory Examples/csharp has a number of simple examples. Visual Studio .NET 2003 solution and project files are available for compiling with the Microsoft .NET C# compiler on Windows. If your SWIG installation went well on a Unix environment and your C# compiler was detected, you should be able to type make in each example directory, then ilrun runme (Portable.NET C# compiler) or mono runme (Mono C# compiler) to run the examples. Windows users can also get the examples working using a Cygwin or MinGW environment for automatic configuration of the example makefiles. Any one of the three C# compilers (Portable.NET, Mono or Microsoft) can be detected from within a Cygwin or Mingw environment if installed in your path.