Using ⎕NET in Dyalog APL to Call .NET Types Directly

Problem and Takeaway

Many Dyalog APL developers need to call .NET libraries or use Windows‑specific APIs that are not available directly from APL. The usual approach is to write a separate native DLL or use a bridge, which adds complexity and deployment overhead. With ⎕NET, available from Dyalog APL 18.0, you can create .NET types, read and write their properties, and invoke methods entirely from APL code, dramatically simplifying integration on Windows.

Prerequisites

• The Dyalog APL version must be 18.0 or newer; earlier releases do not include ⎕NET.
• A supported .NET runtime (Microsoft .NET Framework 4.7+ or .NET Core 3.1+) must be installed and match the APL process architecture (32‑bit APL ↔ 32‑bit .NET, 64‑bit APL ↔ 64‑bit .NET).
• The .NET assembly you intend to use must be accessible to the APL process – either registered for COM interop or placed in a directory that the APL executable can read.
• You need permission to start the APL process with the chosen runtime; on Windows this typically means running the session as a user with rights to load the .NET DLLs.

Step‑by‑Step Procedure

1. Confirm the APL version. In the APL session type ⎕SEND 'VERSION'. The response should show a version number ≥ 18.0. If not, upgrade Dyalog APL first.
2. Verify the .NET runtime bitness. Run ⎕SYSTEM 'echo %PROCESSOR_ARCHITECTURE%' (or use the built‑in ⎕GET environment variable) and compare it to the bitness reported by ⎕GET 'Environment' 'PROCESSOR_ARCHITECTURE'. A mismatch will cause a load failure when you try ⎕NEW.
3. Load the target assembly. If the assembly is not already registered, copy it to a folder that the APL process can see, e.g. C:\APL\Assemblies\MyLibrary.dll. Ensure the file is not blocked by Windows Defender or removed by corporate policies.
4. Instantiate a .NET object. In the session type:

   obj ← ⎕NEW System.Console

   This creates a .NET Console object. The function name matches the .NET type exactly.
5. Read a property. Use ⎕GET to retrieve a property value:

   title ← ⎕GET obj 'Title'

   The result should be an empty string, matching the default Console.Title value.
6. Write a property. Assign a new title:

   ⎕SET obj 'Title' 'Dyalog‑.NET Demo'

   After the assignment, verify the change with another ⎕GET call.
7. Invoke a method. Call a method that returns a value, for example:

   result ← ⎕CALL obj 'WriteLine' 'Hello, APL!'; result

   The variable result will contain the return code (0 for success). If a .NET exception occurs, ⎕CALL returns a non‑zero error code, which you must examine.
8. Handle .NET exceptions. Wrap the call in a trap:

   ⎕TRAP ← 0   ⍝ enable trapping
   obj 'WriteLine' 'This will throw'   ⍝ forces a .NET ArgumentException
   ⎕TRAP ← 1   ⍝ restore normal error handling
   

   If an exception is caught, ⎕GET ⎕ERROR will contain the APL error number, not the .NET exception details.

Verification and Expected Results

After completing the steps, the following checks should succeed:

• ⎕SEND 'VERSION' reports APL ≥ 18.0.
• ⎕GET obj 'Title' returns the string you set in the previous step.
• ⎕CALL returns 0 when the method completes without throwing.
• Running ⎕DISPLAY ⎕GET ⎕NEW System.Console shows the type name System.Console, confirming that the object was created correctly.

Common Pitfalls and Recovery Options

• Bitness mismatch. If APL is 64‑bit but the .NET runtime is 32‑bit (or vice‑versa), ⎕NEW will raise a “Bad image format” error. Install the matching runtime or change the APL process architecture.
• Assembly not found. A “File not found” error indicates the assembly path is incorrect or the file is locked. Verify the folder permissions and ensure the file is not blocked.
• License and redistribution. Commercial use of ⎕NET may require an additional Dyalog license or the .NET runtime to be redistributed with your product. Check the Dyalog licensing terms before shipping.
• Heavy marshaling. Passing large arrays or complex objects between APL and .NET can increase memory consumption and latency. For performance‑critical code, keep data structures simple and avoid deep object graphs.

Conclusion

⎕NET provides a straightforward way to leverage the full .NET ecosystem from Dyalog APL without external bridge code. By confirming version, matching bitness, ensuring assembly accessibility, and using the provided functions, you can create objects, manipulate properties, and invoke methods directly from APL. Verify each step, handle .NET exceptions with ⎕TRAP, and you’ll have a reliable interop solution for Windows‑centric projects.