Declare Method statement - MapBasic - 2023

Purpose

Defines the name and argument list of a method/function in a .NET assembly, so that a MapBasic application can call the function.

Restrictions

This statement may not be issued from the MapBasic window.

Syntax

Declare Method fname Class "class_name"  Lib "assembly_name" 
	[ Alias function_alias ] 
	( [ [ ByVal ] parameter [ , parameter... ] As var_type ]
		[ , [ ByVal ] parameter [ , parameter... ] As var_type... ] ) 
	[ As return_type ]

fname is the name by which a function will be called; if the optional Alias clause is omitted, fname must be the same as the actual .NET method/function name. This option can not be longer than 31 characters.

class_name is the name of the .NET class that provides the function to be called, including the class's namespace (such as System.Windows.Forms.MessageBox)

assembly_name is the name of a .NET assembly file, such as filename.dll. If the assembly is to be loaded from the GAC, assembly_name must be a fully qualified assembly name.

function_alias is the original name of the .NET method/function (the name as defined in the .NET assembly). Note: Include the Alias clause only when you want to call the method by a name other than its original name.

parameter is the name of a parameter to the function.

var_type is a MapBasic data type, such as Integer

return_type is a standard MapBasic scalar variable type, such as Integer. If the As clause is omitted, the MapBasic program can call the method as a Sub (using the Call statement).

Description

The Declare Method statement allows a MapBasic program to call a method (function or procedure) from a .NET assembly. The .NET assembly can be created using various languages, such as C# or VB.NET. For details on calling .NET from MapBasic, see the MapBasic User Guide.

MapBasic programs can only call .NET methods or functions that are declared as static. (VB.NET refers to such functions as "shared functions," while C# refers to them as "static methods.")

At run time, if the assembly_name specifies a fully-qualified assembly name, and if the assembly is registered in the Global Assembly Cache (GAC), MapInfo Pro will load the assembly from the GAC. Otherwise, the assembly will be loaded from the same directory as the .MBX file (in which case, assembly_name should be a filename such as "filename.dll"). Thus, you can have your assembly registered in the GAC, but you are not required to do so.

Examples

Here is a simple example of a C# class that provides a static method:

namespace MyProduct
{
	class MyWrapper
	{
		public static int ShowMessage(string s)
		{
			System.Windows.Forms.MessageBox.Show(s);
			return 0; 
		}
	}
}

In VB.NET, the class definition might look like this.

Namespace MyProduct
  Public Class MyWrapper
	Public Shared Function ShowMessage(ByVal s As String) As Integer
	   System.Windows.Forms.MessageBox.Show(s)
	   Return 0
	End Function
  End Class
End Namespace

A MapBasic program could call the method with this syntax:

Declare Method ShowMessage  
	Class "MyProduct.MyWrapper" 
	Lib "MyAssembly.DLL" (ByVal str As String) As Integer
. . . 
Dim retval As Integer 
retval = ShowMessage("Here I am")

The following example demonstrates how to declare methods in assemblies that are registered in the GAC. Note that when an assembly is loaded from the GAC, the Lib clause must specify a fully-qualified assembly name. Various utilities exist that can help you to identify an assembly's fully-qualified name, including the gacutil utility provided by Microsoft as part of Visual Studio.

' Declare a method from the System.Windows.Forms.dll assembly: 
Declare Method Show    
  Class "System.Windows.Forms.MessageBox"  
  Lib "System.Windows.Forms, Version=2.0.0.0, Culture=neutral, 
PublicKeyToken=b77a5c561934e089"
  (ByVal str As String, ByVal caption As String) 
' Declare a method from the mscorlib.dll assembly: 
Declare Method Move 	
  Class "System.IO.File"
	  Lib "mscorlib, Version=2.0.0.0, Culture=neutral, 
PublicKeyToken=b77a5c561934e089"
	  (ByVal sourceFileName As String, ByVal destFileName As String)
' Display a .NET MessageBox dialog box with both a message and a caption:  
Call Show("Table update is complete.", "Tool name") 
' Call the .NET Move method to move a file 
Call Move("C:\work\pending\entries.txt", "C:\work\finished\entries.txt")