## Interfacing to .Net

### Specifying a call to the .Net environment

You can interface to .Net by supplying `'net'` or `.net` as the environment string (left argument) for ŒNEW, ŒGETCLASS, or ŒCALL. These system functions will allow you to create an instance of a .Net class, or to call a .Net static (shared) method.

### Specifying .Net class names

.Net classes are defined in Assemblies (each assembly usually corresponds to a single .Net library DLL, for example `mscorlib.dll` which contains the basic .Net utility classes), and are organized into Namespaces (such as `System`, `System.Text`, `System.IO` and so on). For example, Microsoft provide a class called `Font` for representing fonts. This is defined in the `System.Drawing` namespace, so its fully-qualified name is `System.Drawing.Font`. The code for this class is held in the System.Drawing assembly, in the shared library `system.drawing.dll`.

When you use ŒNEW (or ŒGETCLASS or ŒCALL) to refer to a .Net class, you can specify the class name in one of the following ways:

- As an undecorated class name, without the namespace qualifier, for example: `'Font'`. In this case, the assembly must be one of those loaded by default or already loaded by a previous call, and the namespace must be included in the namespace search list (see below).

- As a fully (or partially) qualified namespace and class name, for example `'System.Drawing.Font`'. In this case, the assembly must be one of those loaded by default, or already loaded by a previous call, but the namespace does not have to be included in the namespace search list.

- As an undecorated or fully-qualified class name, and a simple file name specifying the DLL in which the assembly can be found, for example: `'System.Data.SqlClient,system.data.dll'`. A comma is used as the delimiter between the class and file name. In this case, the DLL must exist in the standard location known as the Global Assembly Cache (GAC).

- As an undecorated or fully-qualified class name and a full path name specifying the DLL, for example: `'MyBase.MyFirstClass,c:\devt\myclasses.dll'` Again a comma is used as a delimiter between the class and file name.

### Setting the search paths for namespaces and .Net assemblies

When you use ŒNEW (or ŒGETCLASS or ŒCALL) to refer to a .Net class, the system searches through the namespaces and assemblies which are in its search path to resolve the class name. If the class is not found, you will get an error:

          SW„'.net' ŒNEW 'StringWriter'
    Class StringWriter not found in current search list
    DOMAIN ERROR
          SW„'.net' ŒNEW 'StringWriter'
             ^

The above example has failed because `StringWriter` is a class defined in the `System.IO` namespace, which is not included in the default search list. You can set the current search path for .Net namespaces and DLLs by using the system function ŒSETUP and the `'using'` keyword. For example, we can tell the .Net subsystem to include `System.IO` in the search list:

          '.net' ŒSETUP 'using' 'System' 'System.IO'
          SW„'.net' ŒNEW 'StringWriter'
          SW
    [.net:StringWriter]

The namespaces (and optionally DLLs in which they are located) should be supplied as character vectors after the keyword:

          '.net' ŒSETUP 'using' 'System' 'System.Text' 'QMath.Geom,c:\dev\qmath.dll'

Each element comprises either just a namespace (such 'System.Text'), or a namespace followed by the name of the DLL in which it is located. This can be a full path name, or just the name of the DLL (in which case the DLL should be in the Global Assembly Cache).

For convenience, the path is set by default to include the most important .Net libraries, as follows:

    System
    System,system.dll
    System.Text
    System.Collections
    System.Windows.Forms,system.windows.forms.dll
    System.Drawing,system.drawing.dll

You can read the current search list by supplying the 'using' keyword to ŒSETUP with no arguments.

### Conversion of .Net data types to APL data

When your read a .Net property, or call a method which returns a result, APLX by default applies the following data conversion rules:

- Any .Net numeric types (Int32, Int64, single- or double-precision floats, decimal, etc) are converted to APL integers or floats. 64-bit integers are converted to APL floats on 32-bit platforms, to APL integers on 64-bit platforms.

- .Net Booleans are converted to APL binary values 0 or 1

- .Net Strings and Chars are converted to APL character arrays, translated from Unicode to APLX internal representation. (Any characters which do not appear in the APLX character set are converted to question marks.)

- .Net Enumeration types are converted to APL integers (see below)

- Simple .Net arrays are converted to APL arrays, with individual elements converted as above.

Anything else is left as an Object in the .Net environment, and a reference to the object is returned to APL.

There are some special cases to consider. The data might not be convertible at all, or it might lose precision in the conversion. For example, a .Net `Decimal` might have a higher precision than an APL double-precision floating point can represent. To handle cases like this, APLX provides the ŒREF system method. This forces the data to remain as a .Net object. You can then call `ToString`, or other .Net methods appropriate to the `Decimal` data type, to manipulate the data without losing precision.

An example which cannot be represented at all is where a .Net `Double` contains a NaN (Not A Number). APL does not handle NaNs, so it cannot be converted to an APL floating-point value. Instead, NaNs are left as Objects. If you try to use the data in an APL expression, you will get a DOMAIN ERROR, but you can see that it is a NaN and use `ToString` and other operations on it.

### Enumeration Types

Enumeration types are special classes in .Net, which contain sets of alternative values which a particular type of variable can hold (somewhat similar to `enum` types in the C language). When a .Net nethod or property returns an Enumeration type, APLX converts it to the equivalent integer. Equally, calls which expect an Enumeration type can be passed the equivalent integer from APL (the type is converted automatically). This means that Enumerations which are sets of bits can be combined in APL using the + primitive. However, for readability of code, and to avoid having to check the specific value of an Enumeration, you can use ŒGETCLASS to fetch the Enumeration type, and use that directly.

For example, most .Net dialogs (such as OpenFileDialog, which puts up a dialog inviting the user to select an existing file) return a Enumeration type called `DialogResult`, indicating which button (OK, Cancel, etc) was clicked to end the dialog. We can access this class to see what the various enumeration values are:

          DR„'.net' ŒGETCLASS 'DialogResult'
          DR.OK
    1
          DR.OK.ToString
    OK
          DR.Cancel
    2
          DR.Cancel.ToString
    Cancel
          ŒBOX DR.ŒNL 2
    Abort Cancel Ignore No None OK Retry value__ Yes

This means that, if you call the `ShowDialog` method of the `OpenFileDialog`, you can test which button ended the dialog either by checking the numeric value returned, or by seeing if it is equal to the named enumeration value:

          ’R„FileDialog;DR;DLG
    [1]  © Put up file dialog, return file selected or empty vector if none
    [2]   DR„'.net' ŒGETCLASS 'DialogResult'
    [3]   DLG„'.net' ŒNEW 'OpenFileDialog'
    [4]   :If DLG.ShowDialog=DR.OK
    [5]     R„DLG.FileName
    [6]   :Else
    [7]     R„''
    [8]   :End
          ’

### Parameters passed by reference

To handle the (relatively uncomon) cases where a .Net method takes an argument 'by reference', and modifies one or more of the arguments in-situ, you can use ŒSETUP and the `'byref'` keyword. See the documentation for ŒSETUP.

### Using the .Net interface from multiple APL tasks

There are no special restrictions on using the .Net interface from multiple APL tasks. Each task will have an independent copy of the interface, which will be deleted on `)CLEAR`, `)LOAD`, or `)OFF`.

### Inheriting from .Net classes

Your own classes (written in APL) cannot inherit directly from a .Net class. However, you can achieve much the same result by using mixins.

In this example, the constructor of a user-defined class called `APLDate` 'mixes-in' the .Net class `DateTime`

          Œcr 'APLDate'
    APLDate {
    ’APLDate b
    © Constructor for APLDate class
    © Argument is vector of Year Month Day Hour Sec
    © (or just Year Month day)
    © If no argument supplied, use current Œts value
    :If 0=½b
      '.net' Œmixin(›'DateTime'),6†Œts
    :Else
      '.net' Œmixin(›'DateTime'),b
    :End
    ’

    ’r„ts
    © Return .Net DateTime in ŒTS format
    r„Year,Month,Day,Hour,Minute,Second,Millisecond
    ’

    ’r„ts_gmt;gmt
    © Return the date/time adjusted to GMT, in Œts form
    gmt„ToUniversalTime
    r„gmt.Year,gmt.Month,gmt.Day,gmt.Hour,gmt.Minute,gmt.Second,gmt.Millisecond
    ’
    }
          dt„Œnew APLDate

As well as the methods written in APL, all the public properties and methods of the .Net `DateTime` class become available in the APL class `APLDate`:

          dt„Œnew APLDate
          dt.Œnl 2
    Date
    Day
    DayOfWeek
    DayOfYear
    Hour
    Kind
    MaxValue
    Millisecond
    MinValue
    Minute
    Month
    Now
    Second
    Ticks
    TimeOfDay
    Today
    UtcNow
    Year

          dt.ToLongDateString    © Method 'mixed-in' from .Net DateTime
    19 March 2009
          dt.ts                  © Method written in APL
    2009 3 19 16 0 5 0
          dt.ts_gmt
    2009 3 19 21 0 5 0

### Exceptions

If the .Net environment raises an error (or exception), APLX will normally try to print the error message or exception text on the session window, and then raise an APL error (typically DOMAIN ERROR). You can get further information by using ŒLE Last Exception to read back the .Net exception object: For example:

          '.net' ŒNEW 'DateTime' 'Bastille Day'
    Constructor on type 'System.DateTime' not found.
    DOMAIN ERROR
          '.net' ŒNEW 'DateTime' 'Bastille Day'
          ^
          exception„'.net' ŒLE 1
          exception
    [.net:MissingMethodException]

          exception.ŒNL 2
    Data
    HelpLink
    InnerException
    Message
    Source
    StackTrace
    TargetSite

          exception.Message
    Constructor on type 'System.DateTime' not found.

          exception.Source
    mscorlib

          exception.ToString
    System.MissingMethodException: Constructor on type 'System.DateTime' not found.
       at System.RuntimeType.CreateInstanceImpl(BindingFlags bindingAttr, Binder bin
          der, Object[] args, CultureInfo culture, Object[] activationAttributes)
       at System.Activator.CreateInstance(Type type, BindingFlags bindingAttr, Binde
          r binder, Object[] args, CultureInfo culture, Object[] activationAttribute
          s)
       at NetBridge.NetBridge.CreateNamedInstance(String class_name, Object[] arg_li
          st)
       at APLXObj_New(Void* arch_if, Void** objref, wsobj* args, _ExportedProcs* pro
          cs, SByte* errmsg)

### User-interface programming in .Net

User-interface programming in APLX can be done by using the built-in System classes (formerly accessed through ŒWI). This has the advantages that it is relatively easy to do, and that APLX applications using the System classes will work on other platforms (e.g. the Macintosh). But for more flexibility, you can alternatively use Microsoft's .Net classes directly.

User-interface programming using the .Net framework (`System.Windows.Forms`) is a special case of using .Net objects from within APLX. See the Microsoft documentation for full information on this topic.

From the APL programmer's point of view, there are a few specific points to note:

- The typical scenario is that you create a .Net `Form` object, set various properties of the `Form` (such as the `Text` property, which is the window title), and then create further items using control classes such as `Button` and `TextBox`. You need to use the `Add` method of the form's `Controls` property to link up the controls and the form. (Note: If you have a copy of Microsoft Visual Studio or Visual Studio Express, you can use the form designer to design a form interactively, and then copy the dimensions and other properties created in C# or Visual Basic into your APLX code, adjusting the syntax as necessary).

- To handle .Net events, you need to assign the name of an APL callback function (or some other expression) to one of the control's event properties. For example, a `Button` has a `Click` event, which fires when the button is clicked. As with System classes, the event is held in a queue and de-queued using the system function ŒWE, which causes your event handler to be run.

- When one of your callback functions is running, there are three system functions which you can use to find out more about the event. These are:

  ŒEVA Returns a reference to the event argument object (class `EventArgs`)
  ŒEVN Returns the name of the event (such as `'Click'`)
  ŒEVT Returns a reference to the target object, for example the `Button` object

#### Example 1

The following complete example (available in the workspace 10 HELPDOTNET) shows a simple application which displays a window with an edit box, a text box to output results, and a button. When the button is clicked, it simply evaluates the APL expression typed into the edit box and displays the result in the text box. Note in particular the callbacks set up on lines 32 and 33. The first of these (the `Closed` event) is triggered when the window is closed; this terminates the function by clearing the `)SI`, and this in turn causes all the object references to be deleted because they are held in localized variables. The second call back (the `Click` event of the button) causes the `EVALUATE` function to be run.

          ’DOT_Forms;X;F;EditResult;EditIn;ButtonDo
    [1]  © Simple example of using Windows Forms from APLX v4
    [2]  © Create main form
    [3]   F„'.net' ŒNEW 'Form'
    [4]   F.Text„'Expression Evaluator'
    [5]  ©
    [6]  © Create edit box for input line
    [7]   EditIn„'.net' ŒNEW 'TextBox'
    [8]   EditIn.Left„12 ª EditIn.Top„21
    [9]   EditIn.Width„265 ª EditIn.Height„20
    [10]  EditIn.Font„'.net' ŒNEW 'Font' 'APLX Upright' 10
    [11]  F.Controls.Add EditIn
    [12] ©
    [13] © Create multi-line box for result
    [14]  EditResult„'.net' ŒNEW 'TextBox'
    [15]  EditResult.Multiline„1
    [16]  EditResult.Left„12 ª EditResult.Top„50
    [17]  EditResult.Width„265 ª EditResult.Height„180
    [18]  EditResult.Font„'.net' ŒNEW 'Font' 'APLX Upright' 10
    [19]  F.Controls.Add EditResult
    [20] ©
    [21] © Create button
    [22]  ButtonDo„'.net' ŒNEW 'Button'
    [23]  ButtonDo.Left„94 ª ButtonDo.Top„240
    [24]  ButtonDo.Width„100 ª ButtonDo.Height„22
    [25]  ButtonDo.Text„'Evaluate'
    [26]  F.Controls.Add ButtonDo
    [27] ©
    [28] © Make the button accept Enter as equivalent to clicking
    [29]  F.AcceptButton„ButtonDo
    [30] ©
    [31] © Add callbacks
    [32]  F.Closed„'"Cleaning up.." ª …'
    [33]  ButtonDo.Click„'EditResult EVALUATE EditIn.Text'
    [34] ©
    [35] © Show the window
    [36]  F.Show
    [37] ©
    [38] © Process events
    [39]  X„ŒWE ¯1
          ’

          ’A EVALUATE B;RESULT;ŒIO
    [1]  © Evaluate expression B and put it into the Text property of object A
    [2]  © If an error occurs, change the colour of the text
    [3]   ŒIO„1
    [4]   RESULT„ŒEC B
    [5]   :Select †RESULT
    [6]   :Case 0  ©  Error
    [7]     A.ForeColor„A.ForeColor.Red
    [8]     A.Text„MAKEVEC 3œRESULT
    [9]   :Case 1  ©   Expression with a result which would display
    [10]    A.ForeColor„A.ForeColor.DarkOliveGreen
    [11]    A.Text„MAKEVEC•3œRESULT
    [12]  :Else
    [13] ©  2 Expression with a result which would not display
    [14] ©  3 Expression with no explicit result
    [15] ©  4 Branch to a line
    [16] ©  5 Naked branch
    [17]    A.Text„''
    [18]  :End
          ’

          ’R„MAKEVEC B
    [1]  © Given a character array, ensure it's a text vector
    [2]  © If matrix or higher rank, make into CRLF-delimited vector
    [3]   :If 2>½½B
    [4]     R„B
    [5]   :Else
    [6]     R„ŒR ŒBOX B
    [7]   :EndIf
    [8]   R„ŒSS R ŒR(ŒR,ŒL)
          ’

#### Example 2

This function shows a simple example of using the `System.IO` namespace to create a text file and write some text to it. On line [1], it sets up the search path for .Net classes. Lines [2] and [3] fetch the `FileMode` and `FileAccess` enumeration types, which are then used in line [5].

          ’FileWrite;sw;MyFile;FileMode;FileAccess;DateTime
    [1]   '.net' ŒSETUP 'using' 'System' 'System.IO'
    [2]   FileMode„'.net' ŒGETCLASS 'FileMode'
    [3]   FileAccess„'.net' ŒGETCLASS 'FileAccess'
    [4]   DateTime„'.net' ŒGETCLASS 'DateTime'
    [5]   MyFile„'.net' ŒNEW 'FileStream' 'c:\temp\testdotnet.txt'
          (FileMode.OpenOrCreate) (FileAccess.ReadWrite)
    [6]   sw„'.net' ŒNEW 'StreamWriter' MyFile
    [7]   sw.Write 'Written from APLX',ŒR,ŒL
    [8]   sw.Write 'Created by APLX Version 4 at ',DateTime.Now.ToString
    [9]   sw.Close
    [10]  MyFile.Close
          ’

Topic: APLX Help : Interfacing to other languages : Interfacing to .Net

[Next | Previous | Contents | Index ]