Class wwDotnetBridge - West Wind Client Tools

Class wwDotnetBridge

This class allows accessing of .NET classes without requiring COM registration for the .NET classes. It works by hosting the .NET runtime in Visual FoxPro and using a small proxy class to act as a Class Factory for instantiating .NET objects and passing them back for use in Visual FoxPro.

The class works through a couple of DLLs that provide a proxy service for instantiating types and passing them back to VFP. The wwDotnetBridge FoxPro class is simply a front end for the .NET class.

This class supports:

No COM Registration required for accessing .NET Assemblies
Explicit loading of .NET assemblies from disk or the GAC
Support for all .NET 4.0 Runtimes (incl. 4.5.x, 4.6.x, 4.7.x)
Access to most .NET components from FoxPro
Access to Value Types
Access to static values and methods
Access to enumerated values
Access to Generic .NET types
Call .NET methods asynchronously
Many helpers for accessing .NET Arrays, Lists and Dictionaries
Auto-Conversion of many problem .NET types in FoxPro
DataSet conversions to and from XmlAdapter (and from XmlAdapter to cursors)
Support for Task based Async methods with Callback support
Support for calling any .NET method asynchronously
Auto-Conversion of many general FoxPro types to specific .NET types
ToJson() and ToXml() for .NET objects

Getting Started

Somewhere in the startup of your application call InitializeDotnetVersion():

*** Load dependencies and add to Procedure stack
*** Make sure wwDotnetBridge.prg wwDotnetBridge.dll wwIPStuff.dll 
*** are in your FoxPro path
DO wwDotnetBridge
InitializeDotnetVersion("V4")

This ensures that wwDotnetBridge loads with the specified single version of the .NET Runtime that your FoxPro application can load.

Unable to load CLR Instance Errors

If you get an Unable to CLR Instance error when creating an instance of wwDotnetBridge, you probably need to unblock the wwdotnetbridge.dll or need to ensure that the wwdotnetbridge.dll and wwipstuff.dll are in your FoxPro path. Please see Unable to load CLR Instance for more info.

Then when you need to utilize wwDotnetBridge call GetwwDotnetBridge() to get a cached instance and use it to access .NET components:

*** Create or get cached instance of wwdotnetbridge
LOCAL loBridge as wwDotnetBridge, loHttp
loBridge = GetwwDotnetBridge()

*** Create a built-in .NET class and run a method
loHttp = loBridge.CreateInstance("System.Net.WebClient")
loHttp.DownloadFile("http://west-wind.com/files/MarkdownMonsterSetup.exe",
                    "MarkdownMonsterSetup.exe")
DO wwUtils
GoUrl(FULLPATH("MarkdownMonsterSetup.exe"))  && run it

*** Load a custom .NET assembly
loBridge.LoadAssembly("CustomDotnet.dll")

*** Access a .NET component from the new assembly
loItem = loBridge.CreateInstance("Custom.Item")

*** Access properties directly
? loItem.Sku
loItem.Sku = "NewSku"
lnTotal = loItem.CalculateTotal()

*** Access non-accessible properties and methods indirectly
lnFlagValue = loBridge.GetProperty(loItem,"Flag")
lnFlagValue = loBridge.SetProperty(loItem,"Flag",5) 
loBridge.InvokeMethod(loItem,"PassFlagValue",lnFlagValue)

Note that not all properties and methods can be accessed directly as shown on the first example, but some properties and methods require implicit activation as in the 'Flag' example requiring GetProperty(), SetProperty() or InvokeMethod() to indirectly access object members.

If direct access fails, always try the indirect methods.

For much more detailed wwDotnetBridge and .NET Interop information you can also check out the white paper:

wwDotnetBridge White Paper.

Custom
wwDotnetBridge

Remarks

wwDotnetBridge requirements:

Windows 10, 7, 2008 R2, 2012, 2016 or later

.NET 4.5 Runtime or later (4.5.x,4.6.x,4.7.x etc.)

Older versions of Windows and .NET 4.0 are optionally supported by way of wwdotnetbrdige_xp.dll which uses .NET Runtime 4.0 to replace wwdotnetbridge.dll`. Using this DLL you can run on XP, Vista and Server 2003, but only with .NET 4.0 Runtimes. This means you cannot load .NET 4.5 or later components that are common today.

It's also possible to load .NET 2.0 Runtimes (using the V2 version parameter), but we highly recommend you do not use .NET 2.0 as there are security implications and V2 is no longer deployed with Windows 8.1 and Windows 10. 2.0 components can easily be loaded by .NET 4.5+ and that is the recommended path.

Single .NET Runtime Version per FoxPro Process

You can only load a single version of the .NET Framework into a FoxPro app with wwDotnetBridge. To ensure you control the version that you want your application to use, explicitly specify the version when your application starts up, in the main program or main form.
 InitializeDotnetVersion("V4")
Relies on wwipstuff.dll and wwDotNetBridge.dll (.NET 4.0 binary)

Class Members

Member		Description
	ConvertToDotNetValue	Converts a FoxPro value of an 'unsupported' type to a .NET type by either using a FoxPro CAST() or converting the object into a wwDotnetBridge .NET ComValue object. o.ConvertToDotNetValue(lvValue, lcType)
	CreateArray	Creates a new ComArray instance based on the .NET type you specify as a parameter. o.CreateArray(lvArrayInstanceOrTypeName)
	CreateComValue	Creates an instance of a ComValue object which allows you to capture values from method calls and properties and keep them in .NET. o.CreateComValue(lvValue)
	CreateInstance	Creates an instance of a .NET class and passes it back to Visual FoxPro as a COM reference. o.CreateInstance(lcClass, lvParm1, lvParm2, lvParm3, lvParm4, lvParm5)
	CreateInstanceOnType	Allows creation of a new .NET type and assigning that type to a .NET object property without ever going through Visual FoxPro. This allows for creation on non-COM visible types in .NET and indirect manipulation of them. o.CreateInstanceOnType(loInstance,lcProperty, lcClass,lvParm1,lvParm2, lvParm3, lvParm4, lvParm5)
	DisposeInstance	Disposes a .NET object instance. Only works with objects that support `IDisposable`. o.DisposeInstance(loInstance)
	GetDictionaryItem	Returns an item from an `IDictionary` collection by key. o.wwDotNetBridge.GetDictionaryItem(loDictionary, lvKey)
	GetEnumString	Retrieves the string enum field name from a .NET Enum value. o.GetEnumString(lcEnumType, lvEnumValue)
	GetEnumValue	Retrieves a .NET Enumerated value by passing in a string representation and retrieving the corresponding numeric value. o.GetEnumValue(lcType, lcValue)
	GetIndexedProperty	Returns an array value by its index. o.GetIndexedProperty(loListInstance, lnIndex)
	GetProperty	Retrieves a property value from an object instance via Reflection. o.GetProperty(loInstance, lcProperty)
	GetPropertyRaw	Works the same as `GetProperty()`. but while that method returns a fixed up FoxPro friendly value, this method tries to return the raw result value directly as a .NET type. o.wwDotNetBridge.GetPropertyRaw(loInstance,lcProperty,llNoInstanceFixup)
	GetStaticProperty	Retrieves a static property from a .NET type. o.GetStaticProperty(lcType, lcProperty)
	GetwwDotNetBridge	Factory method that can be used to create a `PUBLIC` instance of the `wwDotNetBridge` class. Use this method instead of explicitly instantiating the class to avoid recreating the .NET object wrapper object each time. GetwwDotNetBridge(lcVersion)
	GetwwDotNetCoreBridge	Factory method that can be used to create a `PUBLIC` instance of the `wwDotNetBridge` class. Use this method instead of explicitly instantiating the class to avoid recreating the .NET object wrapper object each time. GetwwDotNetCoreBridge(lcVersion)
	Init	Constructor for the wwDotNetBridge class. Allows specification of the .NET runtime to be used via optional parameter. Last optional parameter determines whether .NET runtime is loaded directly into VFP or whether the .NET component is loaded via COM Interop. o.wwDotNetBridge.Init(lcDotNetVersion, llUseComInterop)
	InitializeDotnetCoreVersion	Use this function in your application's startup program to force the 32 bit .NET Core Runtime version to be used by `wwDotnetBridgeCore` for the entire application. This loads the runtime and thus determines the runtime that will be used for the entire application making calls with `wwDotnetBridgeCore`. InitializeDotnetCoreVersion(lcVersion)
	InitializeDotnetVersion	Use this function in your application's startup program to force the .NET Runtime version to be used by `wwDotnetBridge` for the entire application. This loads the runtime and thus determines the runtime that will be used for the entire application making calls with `wwDotnetBridge`. InitializeDotnetVersion(lcVersion)
	InvokeMethod	Invokes a method on a .NET object instance. o.InvokeMethod(loInstance,lcMethod,lvParm1,...lvParm10)
	InvokeMethodAsync	This useful method allows you to turn any .NET Method you call into an asynchronously called method that returns a callback to you on completion rather than an immediate result. o.InvokeMethodAsync(loCallbackEvents, loInstance, lcMethod, lvParm1-10)
	InvokeMethod_ParameterArray	Like InvokeMethod, but allows passing an arbitrary number of parameters in an array rather than as a named parameter. The array is translated into individual parameters passed into the method called. o.InvokeMethod_ParameterArray(loInst,lcMethod,laParams)
	InvokeStaticMethod	This method allows you to call a static .NET method such as `System.Windows.Forms.MessageBox.Show()` for example. Because the methods are static you can't create an instance and pass it back to FoxPro, instead this method has to be used to invoke a method by using a fully qualified type name instead of an instance. o.InvokeStaticMethod(lcTypeName, lcMethod, lvParm1, ... lvParm10)
	InvokeStaticMethodAsync	Invokes a .NET static method asynchronously on a seperate thread and fires `OnCompleted()` and `OnError()` events into the passed in Callback object. o.InvokeStaticMethodAsync(loCallback,lcTypeName,lcMethod,lvParm1-10)
	InvokeTaskMethodAsync	This method allows you to call any .NET `async` method - any method that returns a `Task` object basically - asynchronously by passing in a callback object that is called back when the async method completes or fails. o.wwDotNetBridge.InvokeTaskMethodAsync(loCallback, loInstance, loMethod)
	LoadAssembly	Loads a .NET assembly into the .NET Runtime currently executing. Note that you should ensure that any required assemblies and dependent assemblies are loaded explicitly into the runtime. o.LoadAssembly(lcAssembly)
	SetProperty	Sets a .NET object property via Reflection. o.SetProperty(loInstance,lcProperty,lvValue)
	SetStaticProperty	Sets a static property or Enum value. Same behavior as SetProperty() but with static properties. o.SetStaticProperty(lcType,lcProperty,lcValue)
	SubscribeToEvents	Allows you to capture events on a source object, by passing in a callback handler that maps the events of the target object with corresponding methods on the handler. o.SubscribeToEvents(loSource, loHandler, lcPrefix)
	ToJson	Creates a JSON string from a .NET object or value passed in. o.ToJson(loDotnetObject)
	ToString	Returns the result from the `.ToString()` method reliably. `ToString()` often is overridden and so not directly accessible via direct COM access. This method internally calls `InvokeMethod()` to call the `ToString()`. o.ToString(loDotnetObject)
	Unload	Unloads the .NET AppDomain and any loaded assemblies within it. o.Unload()
	cErrorMsg	Contains an error message if a method call fails.
	lError	Error flag that can be checked after certain method calls.
	oLastException	Returns the last .NET exception that was caused by a failed operation.

Requirements

Assembly: wwdotnetbridge.prg

Getting Started

Unable to load CLR Instance Errors

Remarks

wwDotnetBridge requirements:

Single .NET Runtime Version per FoxPro Process

Class Members

Requirements

See also: