Dyalog for Microsoft Windows .NET Framework Interface Guide Dyalog version 18.0 The tool of thought for software solutions Dyalog is a trademark of Dyalog Limited Copyright © 1982-2020 by Dyalog Limited All rights reserved. Dyalog for Microsoft Windows .NET Framework Interface Guide Dyalog version 18.0 Document Revision: 20210429_180 Unless stated otherwise, all examples in this document assume that ⎕IO ⎕ML ← 1 No part of this publication may be reproduced in any form by any means without the prior written permission of Dyalog Limited. Dyalog Limited makes no representations or warranties with respect to the contents hereof and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Dyalog Limited reserves the right to revise this publication without notification. email: [email protected] https://www.dyalog.com TRADEMARKS: SQAPL is copyright of Insight Systems ApS. Array Editor is copyright of davidliebtag.com Raspberry Pi is a trademark of the Raspberry Pi Foundation. Oracle®, Javascript™ and Java™ are registered trademarks of Oracle and/or its affiliates. UNIX® is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited. Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries. Windows® is a registered trademark of Microsoft Corporation in the United States and other countries. macOS® and OS X® (operating system software) are trademarks of Apple Inc., registered in the U.S. and other countries. All other trademarks and copyrights are acknowledged. iii Contents Chapter 1: Overview 1 Introduction 1 Prerequisites 3 Files Installed with Dyalog 4 Chapter 2: Accessing .NET Classes 5 Introduction 5 Locating .NET Classes and Assemblies 5 Using .NET Classes 8 Browsing .NET Classes 12 Advanced Techniques 22 More Examples 28 Enumerations 32 Handling Pointers with Dyalog.ByRef 33 DECF Conversion 35 Chapter 3: Using Windows.Forms 37 Introduction 37 Creating GUI Objects 37 Object Hierarchy 38 Positioning and Sizing Forms and Controls 38 Modal Dialog Boxes 38 Non-Modal Forms 43 Chapter 4: Windows Presentation Foundation 45 Introduction 45 Temperature Converter Tutorial 46 Using XAML 46 Using Code 56 Data Binding 65 Example 1 65 Example 2 68 Example 3 70 Example 4 73 Example 5 76 Example 6 82 Example 6a (Casting to DateTime) 84 Example 7 86 iv Example 8 90 Syncfusion Libraries 100 Syncfusion Circular Gauge Example 101 Chapter 5: Writing .NET Classes in Dyalog APL 105 Introduction 105 Assemblies, Namespaces and Classes 106 Getting Started 107 Initialisation 107 Running the Tutorial 108 Example 1 109 Example 2 114 Example 2a 118 Example 3 121 Example 4 124 Example 5 128 Interfaces 132 Chapter 6: Dyalog APL and IIS 135 Introduction 135 IIS Installation Dependency 136 IIS Applications, Virtual Directories, Application Pools 136 Internet Services Manager 138 Chapter 7: Writing Web Services 141 Introduction 141 Web Service (.asmx) Scripts 142 Compilation 143 Exporting Methods 144 Web Service Data Types 145 Execution 145 Global.asax, Application and Session Objects 146 Sample Web Service: EG1 147 Sample Web Service: LoanService 149 Sample Web Service: GolfService 153 Sample Web Service: EG2 170 Chapter 8: Calling Web Services 175 Introduction 175 The MakeProxy function 175 Using LoanService from Dyalog APL 176 Using GolfService from Dyalog APL 177 Exploring Web Services 181 Asynchronous Use 183 v Chapter 9: Writing ASP.NET Web Pages 187 Introduction 187 Your first APL Web Page 189 The Page_Load Event 194 Code Behind 197 Workspace Behind 200 Converting an Existing Workspace 204 Chapter 10: Writing Custom Controls for ASP.NET 217 Introduction 217 The SimpleCtl Control 219 The TemperatureConverterCtl1 Control 221 The TemperatureConverterCtl2 Control 226 The TemperatureConverterCtl3 Control 235 Chapter 11: APLScript 241 Introduction 241 The APLScript Compiler 242 Creating an APLScript File 244 Copying code from the Dyalog Session 245 General principles of APLScript 246 Creating Programs (.exe) with APLScript 247 Creating .NET Classes with APLScript 250 Creating ASP.NET Classes with APLScript 259 Chapter 12: Implementation Details 263 Introduction 263 Isolation Mode 264 Workspace Size 265 Structure of the Active Workspace 266 Threading 269 Debugging an APL.NET Class 271 The web.config file 274 Index 275 Chapter 1: Overview 1 Chapter 1: Overview Introduction This manual describes the Dyalog APL interface to the Microsoft .NET Framework. This document does not attempt to explain the features of the .NET Framework, except in terms of their APL interfaces. For information concerning the .NET Framework, see the documentation, articles and help files, which are available from Microsoft and other sources. The .NET interface features include: l The ability to create and use objects that are instances of .NET Classes l The ability to define new .NET Classes in Dyalog APL that can then be used from other .NET languages such as C# and VB.NET. l The ability to write Web Services in Dyalog APL. l The ability to write ASP.NET web pages in Dyalog APL Chapter 1: Overview 2 .NET Classes The .NET Framework defines a so-called Common Type System. This provides a set of data types, permitted values, and permitted operations. All cooperating languages are supposed to use these types so that operations and values can be checked (by the Common Language Runtime) at run time. The .NET Framework provides its own built-in class library that provides all the primitive data types, together with higher-level classes that perform useful operations. Dyalog APL allows you to create and use instances of .NET Classes, thereby gaining access to a huge amount of component technology that is provided by the .NET Framework. It is also possible to create Class Libraries (Assemblies) in Dyalog APL. This allows you to export APL technology packaged as .NET Classes, which can then be used from other .NET programming languages such as C# and Visual Basic. The ability to create and use classes in Dyalog APL also provides you with the possibility to design APL applications built in terms of APL (and non-APL) components. Such an approach can provide benefits in terms of reliability, software management and re-usage, and maintenance. GUI Programming with System.Windows.Forms One of the most important .NET class libraries is called System.Windows.Forms, which is designed to support traditional Windows GUI programming. Visual Studio .NET, which is used to develop GUI applications in Visual Basic and C#, produces code that uses System.Windows.Forms. Dyalog APL allows you to use System.Windows.Forms, instead of (and in some cases, in conjunction with) the built-in Dyalog APL GUI objects such as the Dyalog APL Grid, to program the Graphical User Interface. Web Services Web Services are programmable components that can be called by different applications. Web Services have the same goal as COM, but are technically platform independent and use HTTP as the communications protocol with an application. A Web Service can be used either internally by a single application or exposed externally over the Internet for use by any number of applications. Chapter 1: Overview 3 ASP.NET and WebForms ASP.NET is a new version of Microsoft Active Server Page technology that makes it easier to develop and deploy dynamic Web applications. To supplement ASP.NET, there are some important new .NET class libraries, including WebForms which allow you to build browser-based user interfaces using the same object- oriented mechanism as you use Windows.Forms for the Windows GUI. The use of these component libraries replaces basic HTML programming. ASP.NET pages are server-side scripts, that are usually written in C# or Visual Basic. However, you can also employ Dyalog APL directly as a scripting language (APLScript) to write ASP.NET web pages. In addition, you can call Dyalog APL workspaces directly from ASP.NET pages, and write custom server-side controls that can be incorporated into ASP.NET pages. These features give you a wide range of possibilities for using Dyalog APL to build browser-based applications for the Internet, or for your corporate Intranet. Prerequisites Dyalog APL Version 18.0 .NET Interface requires Version 4.0 or greater of the Microsoft .NET Framework. It does not operate with earlier versions of .NET. For full Data Binding support (including support for the INotifyCollectionChanged interface1) Version 18.0 requires .NET Version 4.5. The Syncfusion libraries supplied with Version 18.0 require .NET 4.6. The examples provided in the sub-directory Samples/asp.net require that IIS is installed. If IIS and ASP.NET are not present, the asp.net sub-directory will not be installed during the Dyalog installation. 1This interface is used by Dyalog to notify a data consumer when the contents of a variable, that is data bound as a list of items, changes. Chapter 1: Overview 4 Files Installed with Dyalog NET Interface Components The components used to support the .NET interface are summarised below. Different versions of each component are supplied according to the target platform. l The Bridge DLL. This is the interface library through which all calls between Dyalog APL and the .NET Framework are processed l The DyalogProvider DLL. This DLL performs the initial processing of an APLScript. l The APLScript Compiler. This is itself written in Dyalog APL and packaged as an executable. l The DyalogNet DLL; a subsidiary library l The Dyalog DLL. This is the engine that executes all APL code that is hosted by and called from another .NET application. For a list of the files associated with each of these components, see Installation & Configuration Guide: Files and Directories. Code Samples The samples subdirectory contains several sub-directories relating to the .NET interface: l aplclasses; a sub-directory that contains examples of .NET classes written in APL.