Rick Strahl's FoxPro and Web Connection Weblog

What is CORS and how to set it up in West Wind Web Connection

Rick Strahl — Mon, 4 Aug 2025 03:38:39 GMT

CORS stands for Cross Origin Resource Sharing and it's a security feature that you need to be aware of if you're building any Http based REST services that are called from a Web browser and that are accessed across multiple domains. This applies if you have a front-end Web site that runs on one domain, and a back-end server that lives on another domain (or IP address). CORS typically kicks in when making script based requests from a browser for these cross domain calls.

The protocol is an odd one, in that it's typically enforced only by Web Browsers, and not in play for most other Http clients like say wwHttp or XMLHttpRequest in FoxPro, or HttpClient in .NET unless you explicitly mimic the Origin and Access-Allow-Request headers that the protocol uses.

##AD##

When a browser makes a cross-origin fetch() or XMLHttpRequest call from script, it sends a request for CORS headers which the server should respond to with it's own set of response headers. The browser then checks the serverâ€™s response for specific CORS headers like Access-Control-Allow-Origin and Access-Control-Allow-Headers. If the headers match the requesting origin and other headers, the browser allows the calling JavaScript to access the response. If it doesn't match the browser doesn't expose the response to the calling JavaScript Http client and throws a script error on the request.

The purpose of CORS is to allow the server to tell the Web Browser whether it is allowed access to the requested Url. Although CORS has to be implemented by the server, CORS is really a Web Browser security feature that only is enforced by Web Browsers, but not other Http clients.

For example the server may want to ensure that requests only come from one or two domains (origins) that are allowed to access the service when called from a browser. Note that CORS doesn't verify or authorize requests - it's merely a protocol feature that sends requesting headers that are confirmed by the server for a follow-on or in-flight request to process.

Web Browser Only Protocol but implemented by the Server

It's an odd protocol because it's only used in Web Browsers, and mostly irrelevant for other Http clients. The reason is that the actual CORS 'security' feature - rejecting a request on invalid or missing CORS data - is implemented by the Web Browser Http client. So it's up to the client to provide this logic and in general only Web Browsers implement CORS security. Other Http never send CORS request nor do they process them or restrict access based on them.

CORS doesn't fire on localhost

It's also easy to forget about CORS during development, because CORS doesn't kick in when running same origin requests. If your Web page and REST Service run on the same domain/IP Address, there's no CORS. During development that's very common, while deployed applications often run on separate servers. Also if you're using Http testing tools like West Wind WebSurge or Postman, CORS doesn't automatically kick in unless you explicitly provide the CORS request headers like Origin and any Access-Allow-Request-xxxx headers. Hence it's easy to forget to test CORS use cases while testing REST applications. Make a point of remembering and/or ensuring you set up specific tests in your Http client request testing suite (you are using that with your services, right? ??)

The CORS Protocol

CORS is implemented at the Http protocol level via Http headers that are passed from client to server, and back to the client.

It works like this:

The client sends an Origin header and potentially several Access-Allow-Request-xxxx headers
This signals that the server should return a CORS response
The CORS response needs to include at minimum:
- The domain that is allowed access (ie. the current domain)
- The Http Verbs that are allowed
- The Http Headers that are allowed
- Whether security (Authorization, Cookies) is allowed

Depending what type of request you're making CORS data is either made via a separate, pre-flight Http OPTIONS request, or via in-flight headers that are part of a 'normal' request flow.

Pre-flight OPTIONS Request

For most POST, PUT, DELETE, PATCH operations browsers send a pre-flight OPTIONS request to the server which requests a CORS header response. In effect this results in two requests being made to the server by the browser: An OPTIONS request for CORS verification, followed by the original full Http request.

The Http OPTIONS request from client requests only the Http headers for the request and the response returned should contain only the Http headers that a server is expected to return for this request, which includes the CORS headers. The response code should return headers, no data and have a result Status Code 204 No Data although 200 OK with no data also works - the browser doesn't really care about the result code or content, only the headers.

Here's what that looks like:

Figure 1 - A pre-flight OPTIONS CORS request

Note that this is an OPTIONS request that was originally triggered by a POST operation that also requires Authentication in this case. Note that the client sets Access-Control-Request headers to specify what operations it wants to perform which the server response needs to include by adding the corresponding Access-Control-Allow headers. Remember these are typically sent by a Web browser making a cross-origin request via script code.

The server has to respond with headers that include the requested origin, headers and methods. If the CORS headers aren't matched the actual request (ie. the POST request in this case) is never fired and the OPTIONS request fails the original POST operation that initiated this sequence at the client (ie. the fetch() or XMLHttpRequest call).

To clarify the full request flow in this example is:

Browser makes a fetch() request with POST and Authentication
Browser fires OPTIONS request
Server responds with valid CORS response
Browser makes the original POST request
Server responds to POST request

In-flight Request

For simple GET and POST requests that don't include authentication, cookie or custom headers, an Origin header is sent without a separate explicit OPTIONS request and only the single original request is sent. Instead the CORS headers are checked as part of the incoming request and your full response needs to include the CORS headers directly.

Figure 2 - An in-flight CORS request adds CORS headers to the normal request and response headers. Origin is the trigger.

Since in-flight requests don't use a separate request to determine whether the request can execute, it only includes an Origin header to validate that the domain is allowed. Everything else is moot, because the request is already in process. POST operations sometimes send the Access-Control-Request-Headers, but it's not required which means you can't just assume to echo back the Headers that were sent - or not add the CORS headers if you decide to not reject the CORS request.

##AD##

CORS Failure and Success Responses

If the client makes a CORS request and your server code decides it doesn't want to allow the request to process, there are number of ways to do this.

For failures simply return no content with 403 Forbidden, and don't add any of the CORS headers, which effectively fails the CORS request on the client. Any fetch() or XMLHttpRequest call will then fail in JavaScript code.

For a successful OPTIONS response use 204 No Content, make sure to return the CORS response headers and then exit before processing the rest of the request.

For in-flight non-OPTIONS responses, make sure to add the CORS response headers, and continue processing your request as normal. No need to adjust any special Http Response code.

Beware of Access-Control-Allow-Origin: *

In previous versions of Web Connection (and other server frameworks for that matter) the default generated CORS response for 'all origins allowed' was to specify * for the origin value. Although this is a valid value per spec, in recent years several browsers - namely Safari on Mac and iOS - are refusing to accept any * wildcard values for any of the CORS response headers.

For this reason as of Web Connection 8.5 the templates have changed from the old Access-Control-Allow-Origin: * syntax to explicitly retrieving the Origin header and echoing it back in the outgoing header value. The code at the end of this article shows the new approach that works in this more restricted environment.

CORS in Web Connection

Web Connection doesn't have direct support for CORS as part of the low level Web Connection Web Server connectors, so CORS support has to be implemented at the application level. It's an optional feature and typically only needed for REST projects, although in some rare situations you may also need it if you have individual REST requests as part of an HTML application (rare, but it happens).

When you create a new REST project via the New Project Wizard Web Connection automatically adds CORS support into the generated Process class in OnProcessInit(). The code checks for an Origin header and then displays the appropriate CORS response headers, based on the incoming request. This ensures that valid cross-origin requests are properly acknowledged and allowed by the browser.

The semi generic code to do this lives in your Process class in OnProcessInit():

FUNCTION OnProcessInit
LOCAL lcOrigin, lcRequestHeaders, lcVerb

*** Unrelated
Response.Encoding = "UTF8"
Request.lUtf8Encoding = .T.

*** Add CORS headers to allow cross-site access on REST calls for browser access
lcOrigin = Request.ServerVariables("Http_ORIGIN")

IF !EMPTY(lcOrigin) 
	*** Allow all domains IP addresses effectively
	Response.AppendHeader("Access-Control-Allow-Origin", lcOrigin)  
	Response.AppendHeader("Access-Control-Allow-Methods","POST, GET, DELETE, PUT, OPTIONS")	
	
	lcRequestHeaders = Request.GetExtraHeader("Access-Control-Request-Headers")
	if EMPTY(lcRequestHeaders)
	  lcRequestHeaders = "Content-Type, Authorization" && ,Cookie if you use cookie auth!
	endif
	Response.AppendHeader("Access-Control-Allow-Headers", lcRequestHeaders)
	Response.AppendHeader("Access-Control-Allow-Credentials","true")
ENDIF

lcVerb = Request.GetHttpVerb()
IF (lcVerb == "OPTIONS")
    Response.Status = "204 No Content"
	RETURN .F.  && Stop Processing
ENDIF

*** ... other OnProcessInit() code

The code first checks for the Origin client header, which determines whether the request is cross-site and requires the server to return a CORS response. No Origin means no CORS data is required on the request. So local domain access, or access from a non-Web Browser request won't trigger CORS requests.

When a CORS request comes in here are the items required:

Original Origins

Next this code implements the default Origin behavior which returns the origin requested, which effectively allows access to all domains since we're always returning what the client requests.

If you want to allow only certain domains, you can create some sort of lookup function or even a hard code a list of domains to allow. If a CORS request fails you can return a 403 Forbidden status - and not return the CORS headers.

Here's what that looks like:

IF !EMPTY(lcOrigin) 
    IF !THIS.CheckForValidOrigin(lcOrigin)
       Response.Status = "403 Forbidden"
       RETURN .F.
    ENDIF 
    
	Response.AppendHeader("Access-Control-Allow-Origin", lcOrigin)  
    ...
ENDIF

Methods

You need to specify the allowed methods when OPTIONS requests are made. In OPTIONS requests the client will send Access-Control-Request-Methods which you can echo back. Not though that this value is not present in inflight requests so it's better to use a fixed set of Http Verbs that you are planning to use in your project.

Easiest just to return all the methods your app supports, but you could also return the specific verb being requested.

Response.AppendHeader("Access-Control-Allow-Methods","POST, GET, DELETE, PUT, OPTIONS")

Note that in an OPTIONS command you need to include OPTIONS plus Access-Control-Request-Methods rather than just using Request.GetHttpVerb().

Headers

This one is a little tricky since you may not know what headers you need to support for all requests. OPTIONS requests provide an explicit Access-Control_Request-Header value that you can echo back, but again there's no guarantee that this value exists so you want to make sure you have a default value ready using this logic:

lcRequestHeaders = Request.GetExtraHeader("Access-Control-Request-Headers")
IF EMPTY(lcRequestHeaders)
  lcRequestHeaders = "Content-Type, Authorization" && ,Cookie if you use cookie auth or Sessions!
ENDIF

The tricky bit here is that you need to provide all custom headers that you might send. While that may seem easy for individual requests, it's more difficult to figure out exactly what's needed for every request in an application and distill that down to a single set of headers. Hence you'll want to use the requested headers if available. If you have custom headers it'll always trigger an OPTIONS request, so in that case the Allow-Control-Request-Headers should be sent with the incoming request and that's what you should return in your CORS header response.

Allow Credentials

If your app has any authentication you'll want to set this value to true. This is needed if you have Authorization or Cookie headers.

Kind of silly that this is required since the headers should be able to determine whether this is required.

##AD##

Summary

CORS is a clunky protocol and when you first look at it, it doesn't seem to be very effective at providing any security at all. However, for browsers it is useful in ensuring that errand Web browsers can't spoof requests from an embedded iframe for example. The server can explicitly check valid source domains and refuse to serve requests if the list of client domains is not met. However, that does not negate the problem because non-Web Browser clients can call your server any way they want - including potentially spoofed origin domains.

The good news is that it's easy to implement CORS for your REST services in Web Connection. There's only a little bit of code required, and in can be placed into a single entry point in OnProcessInit() in one place. If you're creating new REST projects, Web Connection automatically provides the CORS code in the generated process class and if you have existing code you can easily copy in the code from this article...

this post created and published with the Markdown Monster Editor

Web Connection 8.4 Release Post

Rick Strahl — Wed, 23 Jul 2025 04:32:21 GMT

Hi all,

I've released Web Connection 8.4 which is a minor maintenance release of the FoxPro Web and Service Development framework. The primary reason for this release are several small bug fixes that might be impacting some of you if you are:

Using wwUserSecurity Authentication (especially in Virtual Folders)
You're using Multipart Form Uploads via wwHttp

If that's you and you're using v8.1-8.3, you'll probably want to update to the latest version as soon as possible.

There are also a couple of nice enhancements in wwDotnetBridge, and a new documentation viewer offline application.

Bug Fixes

Let's start with the important bug fixes because they are the main reason for this release.

In the last 8.2-8.3 a regression error was introduced that in certain situations would not properly set the wwUserSecurity related authentication Session cookie. Specifically this can be a problem in scenarios where you're using a non-root virtual folder in your Web application.

I'm not quite sure why this particular error occurred only with virtual folders since Web Connection cookies are always set on the domain root, but for some reason cookies set when running under the virtual in some cases would not be set properly. The issue basically was that a session Id was present but for some reason the session was not recovered and so a new session key gets generated on each check attempt which effectively results in a successful login that lasts only for the current requests. Oddly this only occurs in virtuals and then more likely on nested virtuals (for me it happened in the Web Connection Weblog specifically).

It's fixed now where the code now explicitly generates a new cookie on login rather than checking for an existing cookie to update.

Fix: wwHttp Multipart Form Data Content Type not getting set

This issue is another regression that cropped up from the recent work to support greater than 16mb uploads and downloads. Essentially, the Content Type parameter on AddPostKey() was not being passed through in to the request. It does work for the newly added AddPostFile() but if you're using older code that uses AddPostKey() to upload files the content type was not being appended.

In the process of fixing this bug, I also cleaned up the signature to the AddPostFile() method. The method initially had inherited the same signature as AddPostKey() but there were several parameters that are superfluous for uploading files, so the signature was adjusted for more logical flow.

The change to AddPostKey is a potential breaking change if you were using the method since the order of parameters has changed.

Missing JsonService Variable in wwRestProcess Process Methods

Another regression bug relates to wwRestService and the use of the intrinsic JsonService variable that is passed as a shortcut for THIS.oJsonService into a REST Process method. The error was due a missing PRIVATE scope assignment at the top of the processing pipeline in RouteRequest().

This has been fixed.

New and Improved Features

Not much to report in this update but there are few.

wwDotnetBridge: Unblock all DLLs loaded

The classic .NET Framework still uses Windows Vista Style zoning security by default and so respects the custom blocking attributes that are added to binary files downloaded from the Internet (including files embedded in Zip or 7zip files when unpacked), media devices or from non-local domain drives. Files from those sources get implicitly marked by Windows as 'blocked'.

wwDotnetBridge has for some time explicitly removed blocks on wwDotnetBridge.dll which is the initially loaded Dll that loads the runtime. In most cases that's enough, but I've recently run into cases where other DLLs being loaded were also affected and failed when calling loBridge.LoadAssembly(). For this reason, wwDotnetBridge now also removes blocks from any assembly loaded via LoadAssembly() before loading.

This should improve issues with blocked DLL loading significantly, but you may still run into problems if the DLLs loaded load other DLLs implicitly. In that case you can explicitly load those assemblies using LoadAssembly() (starting with the most deeply nested dependency first), or you can manually unblock files as described in this help topic.

New Offline Documentation Viewer

For years several people here - looking at you Tore - have hounded me to provide offline documentation again as we used some time ago. In the past I created a very large PDF document which was problematic to create as I used Word Automation to import from Html and then Print to Pdf. That process was very brittle and took a really long time to run and often would randomly fail.

Well, recently I switched the documentation over to a new documentation system I've been building called Documentation Monster, which is a Help Builder like system built ontop of my popular Markdown Monster editor.

As part of that tool there's a new option to create a self contained documentation viewer application that can be used to browse the online documentation offline.

Here's what that looks like for Web Connection:

All the functionality of the Web site is available in the offline Viewer so you get all the same docs - offline.

The big benefit from my end is that's easy and fast to build so this documentation is much easier to keep in sync with the online documentation.

The tool produces a self contained EXE that itself is very small. The size of the EXE is determined primarily by the size of the documentation which is embedded inside of the Exe and unpacked when run. That said the Web Connection file is still in the 20mb range zipped due to the huge amount of content and media. The Exe has no dependencies as it runs on the built-in .NET framework.

You can check it out from here:

Download the Web Connection Documentation Offline Viewer

Summary

Overall this is a very small release that's primarily been released for the bug fixes (which have been avaiable for a while in the Experimental Updates Zip file as soon as they were discovered and fixed).

I would recommend updating to the latest version if you are on 8.1-8.3.

Creating and Debugging .NET Assemblies for wwDotnetBridge and Visual FoxPro

Rick Strahl — Fri, 23 May 2025 06:49:41 GMT

If you're using wwDotnetBridge with FoxPro it's quite likely that at some point you'll want to create your own .NET Dlls that interface with external .NET code. While wwDotnetBridge allows you to interface with .NET directly, the code you have to write can be quite tedious because for many things you have explicitly reference the intrinsic methods like InvokeMethod(), SetProperty(), GetProperty() to interact with data that is not compatible over straight COM. While most of these things can be done from FoxPro, the process of doing so is often verbose and in some cases requires multiple objects to be passed around. These intrinsic type scenarios are also relatively slow - compared to native code that is directly executed from .NET. At minimum every .NET call involves a COM call between FoxPro and .NET and when using the Intrinsic methods using Reflection in .NET. It's not horribly slow but compared to native .NET code directly called from .NET it's definitely slower.

Additionally using .NET natively gives you much easier discovery of what's available via the .NET IDE tools that provide rich Intellisense, code completion, CoPilot, Refactoring and easy code navigation. All of this adds up to a richer experience.

Now if you're making only one or two calls into a .NET library from FoxPro it's probably not worth creating a separate .NET component. But if you're making a lot of calls back and forth or the code is performance sensitive, then it may very well be worth your time to create a wrapper .NET compoent that you make one or two consolidated calls to and which then handles many .NET operations or entire component functionality.

I am a big fan of building wrapper components in .NET where you can pass a few key values of input to the wrapper from FoxPro using COM optimized types, and the wrapper then does the brunt of work using native .NET code. If you look at most West Wind components like wwSmtp, wwFtpClient, MarkdownParser, this is exactly how those components are built - there's a .NET class that exposes most of the functionality with a few very focused method calls that combine hundreds of .NET calls and a FoxPro front end abstraction that calls into the wrapper. This is by far my preferred way of exposing functionality from .NET libraries to FoxPro as it optimizes each platform for what it does best.

I know many of you old FoxPro dogs want to do everything in FoxPro, but one of the big advantages of wwDotnetBridge is that it lets you bridge the gap between FoxPro and .NET. It provides an easy on-ramp for experimenting and integrating .NET code into your own applications one piece of code at a time. Whether you implement a single .NET method that you call from FoxPro, a full class, or a whole complex API of components or business objects - you can choose your own pace. Because you're calling a library you can choose how modular you want to go. It's a practical way to create small islands of functionality outside of FoxPro that still can easily integrate with your FoxPro application transparently.

##AD##

Creating your own .NET Components

So when you build a .NET component to interface with, you're going to create a Library Project in .NET. A .NET Class library is essentially library of potentially unrelated classes that doesn't have a 'startup' class. A library is a project without an entry point: It's not a Desktop or Web or Console project, but it's just one or more .NET types (classes, structs, enums etc.) that can be called directly from .NET or... from FoxPro using wwDotnetBridge.

Any .NET class library that you create can be instantiated and called via wwDotnetBridge. IOW - you create a class in .NET, put it somewhere FoxPro can find it and call it with wwDotnetBridge:

do wwDotnetBridge  && load lib
loBridge = GetwwDotnetBridge()

llResult = loBridge.LoadAssembly("bin\MyFirstLibrary.dll")
? loBridge.cErrorMsg  && if there's an error and llResult is false

loPerson = loBridge.CreateInstance("MyFirstLibrary.Person")
loPerson.Firstname = "Rick"
loPerson.Lastname = "Strahl"
loPerson.Address = loBridge.CreateInstance("MyFirstLibrary.Address")
loPerson.Address.Street = "999 Emergency"
loPerson.Address.PostalCode = "97000"
loPerson.Entered = DATETIME()
loPerson.Save()

To create a minimal .NET project literally takes two files: A project file and a source code file that contains one or more classes that can be called. If you need more classes or components you can add them to the same file or create new classes. The new .NET project system automatically picks up and compiles all source files it finds so it's easy to add functionality.

There are a number of ways to create a new project, but due to the fact that recent versions of Visual Studio and the dotnet new CLI don't include templates for new .NET Framework (net4.x) projects.

While you can use the tooling, but my preferred way of doing this is just creating the project file and the main class by hand (or copying an existing project template from here).

There are two reasons for this :

.NET Tools (Visual Studio and the dotnet CLI) don't support creating new .NET 4.x projects
It's easy to copy a couple of files to disk

Although neither Visual Studio, the dotnet command line or VS Code support creating .NET Framework projects, you can definitely build them once created. They are just hiding .NET Framework projects because Microsoft is trying to push everyone to .NET Core.

However, I highly recommend that you create .NET Framework (.NET 4.x) projects rather than .NET Core projects for your components unless you have a pressing need for .NET Core features or you need to interface with another library that does not support .NET 4.x or .NET Standard 2.0 which both can be used with the built-in .NET Framework.

The reason is simply that the .NET Framework is built-into Windows so there's nothing to install. You can create a .NET Framework project compile and run without any other requirements other than the tiny DLL created (plus any dependent assemblies your component references). .NET Core on the other hand requires that a compatible runtime is installed, which means you have to make sure that your application checks and deploys the right runtime. There's no such requirement for .NET Framework.

If you build for .NET Framework chances are that you can also move the code to .NET Core easily by adding a second target, so this is not a 1-way street or you can multi-target and actually support both. Difference between them are slight especially if you stick to core functionality.

##AD##

Creating a new Project 'by hand'

There are a number of ways of creating a .NET project, but here's what I do:

Create a new folder
Open Visual Studio Code in that folder initially (or any other editor)
Create the following two Files in there (Project and first component)
Use the command line tools to build and run to test the component

I do this even if I have Visual Studio installed. Why? As mentioned neither Visual Studio or the dotnet new CLI has support for .NET framework. While you can create a new project for netstandard2.0 which is close to what you need - you need to make a few small changes to the project. So rather than screw around with this changing template and remove things that don't work, I use either a template from disk or manually create the files and copy in the small bits of project and initial class code.

Start by creating creating a new folder for your project and opening an editor there:

# create and goto  directory
cd D:\wwapps\Conf\wwDotnetBridgeRevisited\Dotnet\FirstLibrary

# Open VS Code in folder mode
code .

Create two files:

FirstProject.csproj
Person.cs

Here's the project:

<!-- FirstLibrary.csproj -->
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>    
    <TargetFramework>net472</TargetFramework>    

    <!-- Optional: Output to a specific folder. Relative or absolute -->    
    <OutputPath>..\..\bin</OutputPath>
    <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
   
  </PropertyGroup>
</Project>

This sets the target .NET 4.72 or later and puts the output DLL into the specified folder. The folder is optional - if you don't specify it goes into a deep folder hierarchy below the project. Typically you don't want this.

Personally I like to put all my .NET assemblies either into my application's root folder (if there's only one) or .\BinSupport folder below it for many Dlls.

Next you need to create at least a single .cs source file with a class in it. I'll create the Person and Address classes I used in the previous example here:

using System;
using System.Collections.Generic;

namespace FirstLibrary
{
    public class Person
    {
        public string Firstname {get; set; }
        
        public string Lastname {get; set; }
        
        public DateTime Entered {get; set; }  = DateTime.Now;

        public Address Address {get; set;} = new Address();
        
        public bool Save()
        {
            // do whatever to save here
            return true;
        }

        public override string ToString()
        {
            return Firstname + " " + Lastname ?? string.Empty;
        }
    }

    public class Address
    {
        public string Street {get; set; }
        public string City {get; set; }
        public string State {get; set; }
        public string Zip  {get; set; }

        public override string ToString()
        {
            return Street + "\r\n" + City + "\r\n" + State + " " + Zip;
        }
    }
}

Next we need to build the project. You can open a Terminal (Powershell here) either in Visual Studio Code or directly on the command line in the project folder and then build the project.

dotnet build FirstLibrary.csproj

This builds the project into the output folder which happens to live below my FoxPro project folder as ,\bin.

I can then call the and the component from FoxPro with:

CLEAR
do wwDotnetBridge  && load lib
loBridge = GetwwDotnetBridge()

llResult = loBridge.LoadAssembly(".\bin\FirstLibrary.dll")
? loBridge.cErrorMsg  && if there's an error and llResult is false

loPerson = loBridge.CreateInstance("FirstLibrary.Person")
loPerson.Firstname = "Rick"
loPerson.Lastname = "Strahl"
loPerson.Address = loBridge.CreateInstance("FirstLibrary.Address")
loPerson.Address.Street = "999 Emergency"
loPerson.Address.City = "AnyTown"
loPerson.Address.PostalCode = "97000"
loPerson.Entered = DATETIME()
loPerson.Save()

? loPerson.ToString()

Altogether it looks like this:

The above does:

Builds the project and compiles into the app folder (....\bin)
Open FoxPro
Runs the test.prg file

Cool it works.

Shutting down Visual FoxPro to Unload .NET Assembly

.NET and any components cannot be unloaded once loaded, so in order to update the DLL you have to shut down the host process, which in this case is Visual FoxPro (or your app EXE).

If you need to make any changes to the DLL code, you need to:

Shut down Visual FoxPro (or EXE)
Rebuild the .NET project
Restart Visual FoxPro

To make this cycle a little easier I tend to create a small Powershell (or Command) script that I can run from the terminal in the project folder:

dotnet build .\FirstLibrary.csproj

if ($LASTEXITCODE -ne 0) {
    exit
}

$startdir = $pwd

Set-Location ..\..
& D:\programs\vfp9\vfp9.exe
Set-Location $startdir

This script handles building the project and launching VFP. It doesn't shut down FoxPro first - you'll have to do that manually, but building and starting up FoxPro is handled to make the launch a bit quicker than manually fumbling around to launch VFP in the right place.

All of this works fine and it's pretty low impact so far. No need to install anything beyond the .NET SDK and VS Code (or your editor of choice).

But things could be a little more integrated. And that's where Visual Studio comes in.

If you want:

A smoother build and run cycle
Ability to debug your DLL

then using Visual Studio is a worthwhile upgrade to the dev process.

Opening the Project in Visual Studio

Although I used Visual Studio Code (or no editor/IDE at all) to create the project originally, I can now also open this project in Visual Studio by opening the FirstProject.csproj from Explorer and selecting Visual Studio to open:

Figure 4 - Opening the project in Visual Studio lets you build and run more interactively

From here you can build (right click Build or Rebuild) or you can Debug the project with the debugger using the green run button.

In order for that to work we need one more file to configure how to 'launch' our Dll. Create a launchsettings.json file that contains the startup options (you can also do this from Properties ? Debug ? Open Debug Launch Profiles Ui but it's easier to create the file manually):

{
  "profiles": {
    "VFP (Debug)": {
      "commandName": "Executable",
      "executablePath": "d:\\programs\\vfp9\\vfp9.exe",    
      "workingDirectory": "D:\\wwapps\\Conf\\wwDotnetBridgeRevisited\\Dotnet\\FirstLibrary"
    }
  }
}

This file specifies the path to the Visual FoxPro IDE (or if you prefer your application executable) and the folder that you want to start it in, which is your FoxPro project folder. From there you can then run your application or test program as I did in the example above.

Debugging

For debugging it's important to understand that you are driving the debugging process through Visual Studio/.NET rather than through your FoxPro application. Visual Studio launches FoxPro or your application, and you then run the code that eventually hits the .NET code that you have a breakpoint on. But Visual Studio is in control of the process and FoxPro is just the target that actually calls into .NET code you are debugging.

Note that you can debug your own code .NET readily enough, but in most cases you can't debug external, system or third party .NET code unless debug information (.pdb) file is provided by the vendor.

So, with the Launch profile configured we can now run the application in Debug mode. When running in Debug mode you can now set breakpoints in your code, and the debugger then stops on those breakpoints:

Figure 5 - Stopped on a breakpoint in the Visual Studio Debugger.

When on a breakpoint you can examine values using the Locals and Watch windows, but you can also hover over any active values or properties to display their values. From there you can continue to step over code using all the standard over, into, out step operations you're familiar with.

Another nice feature: The debugger supports hot reload, which means you can make changes to some code while the app is running. If you've changed code that's already executed, you can move the execution pointer back to before the edit location and the code runs again with the newly compiled code. This can be a huge time saver when you're fixing code and trying to get it to work correctly.

This example doesn't use any external libraries, but if you were interfacing with other libraries things work exactly the same. Again - debugging is limited to your own code in most cases.

And that's it! With this you have all you need to build, run and debug your .NET components.

VS Code also supports debugging and there's also a commandline debugger available. However, those debuggers only work with .NET Core and even then they don't work very well with an external process to attach to.

##AD##

Summary

If you're using wwDotnetBridge it's a good idea to take advantage of .NET as best as you can by avoiding excessive .NET code written from FoxPro code using wwDotnetBridge functions. If you're writing copious amounts of wwDotnetBridge code in FoxPro it's time to think about offloading that code into a .NET class or component that you can abstract and call from FoxPro with a simpler and much less chatty interface.

Building .NET libraries is much easier than it used to be in days past, either using the no-IDE command line tooling, or if you want the IDE experience with a somewhat less intrusive Visual Studio installation. The tooling is drastically better and less intrusive to install than it used to be a few years ago.

By using .NET code for more complex tasks you can make development of your code easier, and also improve performance by avoiding a chatty COM interop interface calls for every member access. While performance of wwDotnetBridge both with native COM calls and Reflection intrinsic method calls, doing those calls directly in .NET is still considerably faster.

I highly recommend this approach on anything that exceeds a few lines of .NET code that you need to call from FoxPro. .NET code is compact and you can cram many different components into a single tiny DLL that you can ship with your application with little to no overhead. And since you're using wwDotnetBridge already anyway having one extra DLL is not an issue.

Finally, by offloading some processing into .NET you have a chance to learn something new at your own pace. Because wwDotnetBridge interfaces deal with components you can create components large and small to move small chunks of your application to .NET that you can perhaps use in the future in other projects or if you decide to migrate in the future.

Resources

FoxPro Running on a Windows ARM Device

Rick Strahl — Thu, 7 Nov 2024 08:42:14 GMT

I recently picked up a Windows ARM device in the form of a Samsung Galaxy Book 4 with a SnapDragon X Elite chip. Best Buy had a sale going for $799 at the time, and so I 'snapped' one up.

I was pleasantly surprised that almost all of my Windows applications run without issues. This is true for both .NET and FoxPro applications as far as my own apps are concerned, and just about anything else in my typical Windows application and tools collection.

##AD##

FoxPro and Web Connection

One of the things I was really curious about was whether FoxPro applications would work. After all FoxPro is a 32 bit application (ie. not x64) and it's based on 30 year old Windows code.

In fact, to test out FoxPro operation under ARM I tried the following from scratch:

Install Visual FoxPro and SP2-HF3
Copy over my Web Connection Dev folder from my main laptop

Then proceeded to fire up FoxPro in my dev folder and ran:

Launch()

which in my setup launches the Web Connection .NET Core Web Server.

To my delight, everything fired right up and ran on the very first try - without any changes whatsoever:

Full disclosure: I did already have the .NET 8.0 SDK installed in order for the .NET Core server to run

The Web Connection FoxPro server runs fine under ARM in x64 emulation mode, but surprisingly performance is very good. Since this is a Windows Home machine full IIS is not an option, but I was able to set up IIS Express on this machine and it too just works on the first try:

IIS Express runs in x64 emulation but that's also not a problem and performance seems to be on par with the .NET Core version. That performance of emulation is almost on par with the native .NET Core server's ARM binary is almost more impressive than the .NET server running without any changes at all.

Neither the native .NET Core server or the Web Connection Module under IIS Express feel laggy and request hits are in a the 5-10ms range which is a only little slower than what I see on my i9 development laptop (trending towards the higher end of the range on ARM vs. lower end on I9).

Earlier also fired up West Wind Html Help Builder, which is a FoxPro desktop application running with a FoxPro runtime installation and it also worked without any issues. That app does a lot of oddball things with FoxPro UI, ActiveX controls, the WebBrowser control and native Win32 calls. Yet it just runs without any issues.

Pretty cool!

Everything works - except SQL Server!

When I picked this machine up and started installing my typical developer and productivity workload on it, I was expecting a lot of stuff to not work or work badly through emulation. It turns out I was wrong! Mostly!

Just about everything works!

I've been pleasantly surprised in that just about everything works - either via many native ARM applications that are now becoming available, or via the built in and 'not bad at all' x64 emulation.

There are a few things that don't work well - older versions of SnagIt for example don't want to capture system windows correctly and my audio software was having problems keeping the external audio interface connected. Mostly edge cases, but be aware there are somethings - especially hardware or low level windows stuff - that can have problems.

The one let down is that performance is not quite as impressive as was ~~advertised~~ hyped. It feels like there's quite a bit of lag, especially during application startup initially. Performance overall feels at best like a mid-level laptop, certainly not something that would replace a higher end developer I7/I9 laptop for me, which I had expected given the promotional hype. Even local AI operations using Ollama which is what these machines were supposed to be best at are only barely better for local AI processing compared to my I9 and low-midrange nVidia card equipped laptop do.

.NET Applications - Just Run Natively!

What is quite impressive though is that all of my .NET apps, - including a several complex Windows Desktop applications - ran without even recompiling, natively under ARM64. Markdown Monster and West Wind WebSurge both run without any changes and I have yet to find any problems on ARM. All of my Web apps also 'just run' under ARM64 and I have yet to see any errors or operational differences. That's impressive - especially for the desktop apps which use a ton of P/Invoke and native code in addition to raw .NET code. And it... just... works!

The one thing that was problematic: SQL Server

The only real issue I ran into was SQL Server, which does not have an installer from Microsoft that works with Windows ARM.

There are two workarounds that I discuss in a separate post on my main blog:

Using LocalDb with Named Pipes
Using a hacked installer to install SQL Express or SQL Developer

If you need to work with a local copy of SQL Server check out the post that goes into greater detail.

##AD##

Summary

So, the good news is ARM devices have a lot going for it. There are now many native ARM applications available - most mainstream applications have ARM specific versions or can run under ARM. Most .NET applications can automatically run natively on ARM if they are compiled for AnyCPU mode.

For those apps that don't have native support x64 Emulation is surprisingly good and fairly fast. Frankly I'm not sure that I can really tell the difference from emulation to native - emulated apps seem a little slow to start up, but once running the emulation seems as fast as I would expect for this machine's processing power (ie. a mid-level business laptop).

In summary ARM device compatibility is much better than I expected and performance is about on par what I thought it would be, but a bit below the expectations that were hyped up for ARM devices.

All of this is great news for FoxPro it extends the lifetime of FoxPro just a little longer yet... who would have thunk it?

this post created and published with the Markdown Monster Editor

Web Connection 8.1 Release Post

Rick Strahl — Mon, 14 Oct 2024 22:29:02 GMT

Hi all,

Web Connection 8.1 has been released. This update is mostly a maintenance release that cleans up a few small bugs and issues, but it also introduces a few notable improvements:

Support for greater than 16mb Web Response output
More improvements to COM server handling
Improved wwDotnetBridge stability (no more crashes after full memory unloads)

Let's take a look.

Support for greater than 16mb Web Response Output

Back in the Web Connection 5.0 days Web Connection switched from file based output to string based output, which it turns out is a lot faster and more flexible than direct file based output. File based output was able to write output of any size as the file content can be written out to any size. String based output on the other hand is - potentially - subject to FoxPro's 16mb memory limit. In version 5.0 Web Connection introduced the wwPageResponse class which switched to an in memory buffer that builds up a string for output.

Essentially it does:

FUNCTION Write(lcText,llNoOutput)

IF !THIS.ResponseEnded
   THIS.cOutput = this.cOutput + lcText
ENDIF  

RETURN ""
ENDFUNC

FoxPro 9.0 is extremely efficient at string concatenation and at the time this provided a large boost in performance - especially related to the complexities of the then introduced Web Connection Web Control Framework (now deprecated) which relied on tons and tons for small components to write small bits of code.

But... with that change came the limitation related to FoxPro's 16mb string limit. Ironically the way Web Connection's response class was designed - unintentionally I might add - the above code for string concatenation actually works just fine even for strings larger than 16mb. Unfortunately, the code would fail later on when writing out the entire response including the headers which required an incompatible string operation.

Specifically it's this code:

*** This fails if cOutput > 16mb
RETURN this.RenderHttpHeader() + THIS.cOutput

This is one of the quirks of the 16mb string limit in FoxPro: You can actually create larger strings, but you cannot concatenate or send a greater than 16mb string to another operation that modifies the string. Essentially that code above in the wwPageResponse::Render() method broke the code.

I wrote in more detail about the workaround to this issue in a previous Blog Post here if you're interested:

Making Web Connection Work with Response Output Greater than 16mb

The post includes the actual changes in Web Connection along with the code work around and the helpers - you might find those helpers useful in your own code that has to deal with large strings.

The key bit of code that uses the updated string processing is in wwProcess.CompleteResponse():

LOCAL lcResponse, lcHttp, lnX, loCol

*** Grab the response content
lcResponse = this.oResponse.Render(.T.)

*** IMPORTANT: Must follow the Render() as Render() may add headers (GZip/Utf8 etc)
lcHttp = this.oResponse.RenderHttpHeader() 

*** Check for 16mb+ output size
IF LEN(lcResponse) > 15800000    
   loCol = SplitStringBySize(lcResponse,5500000)   
   lcResponse = ""
   FOR lnX = 1 TO loCol.Count
       lcHttp = lcHttp + loCol.Item(lnX)
   ENDFOR
   loCol = null
ELSE    	
   lcHttp = lcHttp + lcResponse
   lcResponse = ""
ENDIF

IF THIS.oServer.lComObject
  *** Assign text output direct to COM Server output
  THIS.oServer.cOutput= lcHttp
ELSE
  FILE2VAR(this.oRequest.GetOutputFile(),lcHttp)
ENDIF
lcHttp = ""

In a nutshell, the code change involves breaking up the large string into a collection of smaller strings, and then building a new string that adds the headers first and then appends the all of the string chunks which now allows for >16mb for both headers and content.

This way there's never a >16mb string on the update side or right side of = assignment operation and so we can write strings of any size, memory permitting (and yes you can run out of memory). It's a hack and ends up costing some extra memory overhead as strings are duplicated, but it works surprisingly well and it now allows us to return very large HTTP responses in memory.

When working with large strings like this, you'll want to clear any in progress strings and the collection as soon as you no longer need it to avoid holding on to memory any longer than you have to.

To be clear Web Connection has had support for more than 16mb output via file operations - using Response.DownloadFile() and Response.TransferFile() which can serve content of any size. But it's a bit more complicated to generate output to file first and then be able to delete the content after it's been sent.
(I'm thinking of another enhancement to allow for file deletion after sending in a future update)

Another related hack for large HTTP text results (HTML, JSON etc.) is to use Response.GzipCompression = .T. which reduces the size of the HTTP output before headers are even added. Especially in the case of JSON compression can often knock down the size of a JSON document by more 5x since there's a lot of repetitive data in JSON or XML documents. There's more info in the above blog post.

There are a couple wwPageResponse class changes that are related to the above changes:

A new wwPageResponse::WriteFullResponse(lcData) This method writes out a full response by overwriting any existing data. Added to both wwPageResponse, and wwResponse.
wwPageResponse.Render(llOutputOnly)
The Render() method has a new llOutput parameter that returns only the response content without headers. Render() by default returns both headers and content and this override is used when creating the final output that's sent back to the Web server in file or COM based output.
SplitStringBySize() in wwutils.prg
This splits a string into a collection string chunks. This function is used to split out the >16mb content into smaller strings before being reassembled into a single string including the header.
JoinString() in wwutils.prg
The opposite of the above - takes strings in a collection and returns a single string.

Improvements to COM Server Handling

Web Connection 8.0 has introduced improved COM Server loading, which drastically speeds up COM server loading and provides a lot more checking deterministic termination of servers that cannot be shut down via COM either because they are still busy or have been otherwise orphaned. In the past this has been an ongoing problem for those that were running large numbers of COM Server instances as it took a) very long to load many instances and b) could result in orphaned server instances that would never be shut down - ie. a lot of extra EXEs in task manager.

v8.0 addressed both of these issues with parallel loading of COM servers, immediate server startup while others are still loading and a more robust shutdown sequence that tries to shut down all instances of a given executable as opposed of just the actual process ids of servers that are being shut down.

It took a bit of experimenting during the beta of v8.0 to get this right - many thanks to Richard Kaye during the original beta, and Scott Rindlsbacher during the v8.1 cycle, who kindly both were willing to test with large production and staging environments.

In v8.1 we identified an outlier issue that caused issues with COM server loading for large server pools due to a hard coded timeout that was causing the server pool to not complete loading. This would result in the server load cycle to error out and then try to reload again, going through a rather unpleasant re-cycling loop.

In this update I've made the server load timeout configurable and allow for a larger timeout to begin with. So this is much less likely to run up into the timeout in the first place and if it still occurs can be adjusted with a larger timeout.

The new timeout logic allows for 2 seconds per server to load. That should be plenty, plus parallel loading should reduce the overall time significantly. So if you have 10 servers the load timeout is 20 seconds. If it really takes that long to load servers - there's probably something wrong with the server, as it should not be that slow to load ??

For reference the original release had a max timeout of 5 seconds with 1 second load time per server. I had figured that this would be enough given that parallel loading would ensure that servers load somewhere around maybe 2x their individual load time. But it turns out that if you run in a processor constricted environment that is not uncommon on virtual VPC machines you may still end up loading sequentially. For this reason I removed the max value and stick with the per server load timeout that is configurable.

The new value is in configuration in web.config (Web Connection .NET Module):

<add key="ComServerPerServerLoadTimeoutMs" value="2000" />

Or in WebConnectionServerSettings.xml (.NET Core Web Connection Web Server):

<ComServerPerServerLoadTimeoutMs>2000</ComServerPerServerLoadTimeoutMs>

Improved wwDotnetCoreBridge Stability

In relation to my wwDotnetBridge talk at Southwest Fox I did a bunch of work surrounding wwDotnetBridge.

One issue that's been coming up a few times has been that the new wwDotnetCoreBridge class has been somewhat unstable. In previous releases the library worked fine, but it would fail if FoxPro does a full memory reset via CLEAR ALL or RELEASE ALL etc. What was happening is that unlike the full framework version of wwDotnetBridge, the .NET Core version would clear out all of its memory as the native Windows interface would not pin the loader code in memory.

Thanks to an issue report and some great sleuthing by @horch004 who found the workaround by pinning the loader DLL into memory and thereby ensuring that the memory would not be wiped a FoxPro memory clearing operation.

The fix for the Core is to pin the DLL and then simply return the already loaded .NET wwDotnetBridge instance and that works great - no more crashes after a full memory wipe.

Breaking Change: Updated Log Format

In this release the Web Connection log format has been updated for two things:

Widened the RemoteAddr field to support ipV6 addresses
Added a Size field to log the response size (if response is captured)

To deal with this you need to update the wwRequestLog FoxPro table or the corresponding SQL table.

For FoxPro

Delete the wwRequestLog.dbf table. It'll be recreated with the new file structure when Web Connection re-starts.

For Sql Server

Update the table using SQL commands or manually in your SQL Admin tool (changed fields separated below):

CREATE TABLE [dbo].[wwrequestlog](
	[time] [datetime] NOT NULL DEFAULT getdate(),
	[reqid] [varchar](25) NOT NULL DEFAULT '',
	[script] [varchar](50) NOT NULL DEFAULT '',
	[querystr] [varchar](1024) NOT NULL DEFAULT '',
	[verb] [varchar](10) NOT NULL DEFAULT '',
	[duration] [numeric](7, 3) NOT NULL DEFAULT 0,
	
	[remoteaddr] [varchar](40) NOT NULL DEFAULT '',
	
	[memused] [varchar](15) NOT NULL DEFAULT '',
	[error] [bit] NOT NULL DEFAULT 0,
	[reqdata] [text] NOT NULL DEFAULT '',
	[servervars] [text] NOT NULL DEFAULT '',
	[browser] [varchar](255) NOT NULL DEFAULT '',
	[referrer] [varchar](255) NOT NULL DEFAULT '',
	[result] [text] NOT NULL DEFAULT '',
	
	[size] [int] NOT NULL DEFAULT 0,
	
	[account] [varchar](50) NOT NULL DEFAULT ''
) ON [PRIMARY]

Summary

There you have it. Web Connection 8.1 is a minor update and other than the logging table changes for SQL there are no breaking changes. As always you can update the project by checking out the update topic in the documentation.

If you run into any issues please post a message on the message board:

Web Connection Support

this post created and published with the Markdown Monster Editor

Making Web Connection Work with Response Output Greater than 16mb

Rick Strahl — Tue, 1 Oct 2024 01:30:22 GMT

During this year's Southwest Fox conference and Scott Rindlisbacher's session, he was discussing generating very large JSON output using West Wind Web Connection with output that exceeds 16mb as part of his application using REST JSON services. The issues raised where two-fold:

Output over 16mb would fail
Large output was too slow to travel to the client

My first thought was that I had addressed the >16mb issue previously, but after some initial testing it's clear that that was not the case! Web Connection in the past has been limited to 16mb output due to FoxPro's 16mb string limit, for direct Response output. Although there are ways to send larger output via files, that can be a lot more complicated.

During the conference I spent some time to create a solution to this problem and Web Connection can now serve content >16mb. If you're on Web Connection 8.0 and you want to experiment with this updated support, you can pick up an experimental update here:

Web Connection Experimental (v8.1)

These features will be shipped with the next release in Web Connection v8.1.

If you're interested, what follows is a discussion on how I worked around this limitation along with a review of how you can create string content that exceeds 16mb in FoxPro in general.

##AD##

Making >16mb Output work in Web Connection

So while at SW Fox I started playing around with some ideas on how to make >16mb content work, and implemented a solution to this problem.

The solution hinges around intercepting output that is returned and ensuring that no parts of the output strings that are being sent are >16mb, and if they are splitting up those strings into smaller chunks that can be concatenated.

If you want to learn more about how you can use >16mb strings in FoxPro, you can check out my post from a few years ago that shows how this can work if you are careful in how you assign large values.

Working with >16mb Strings

You can assign >16mb by doing something like lcOutput = lcOutput + lcContent, but no part of a string operation that manipulates a string and updates can be larger than 16mb.

The left side of the = can become larger than 16mb, but the right side can never be greater than 16mb.

You also cannot call functions that changes the value of a >16mb string but some functions can return a greater than 16mb string.

Web Connection is already build on incremental building of a string in memory by doing effectively:

FUNCTION Write(lcData)
THIS.cOutput = this.cOutput + lcData
ENDFUNC

which allows writing output >16mb as long lcData is smaller than 16mb. Most of Web Connection's implementation features run through the Response.Write() or friends methods, including complex methods like Response.ExpandScript() and REST Process class JSON output, so as long as no individual Response.Write() operation writes data larger than 16mb, all output automatically can be larger than 16mb.

wwJsonSerializer already supported >16mb JSON output, and with the changes I added this week any response larger than 16mb is chunked into the actual Response output (so there the content effectively gets chunked twice - once for the JSON and once for header/httpoutput).

The issue with the actual HTTP output is that Web Connection pre-pends the HTTP headers in front of the HTTP response. The HTTP response can be larger than 16mb, but if we prepend the headers in front of a 16mb string - that doesn't work (ie. right side of = >16mb).

The workaround for this is: Chunking the string into smaller block that can be written (5mb chunks).

lcHttp = Response.RenderHttpHeader()
lcHttp = lcHttp + Response.GetOutput()  && This fails if the response is >16mb

To fix this I ended up creating a small helper function that splits strings by size to take the string that is larger than 16 megs and splitting it into chunks.

*** Inside of wwProcess::CompleteResponse()
LOCAL lcResponse, lcHttp, lnX, loCol
lcResponse = this.oResponse.Render(.T.)

*** IMPORTANT: Must follow the Render as it may add headers
lcHttp = this.oResponse.RenderHttpHeader()

IF LEN(lcResponse) > 15800000    
   loCol = SplitStringBySize(lcResponse,5000000)  
   FOR lnX = 1 TO loCol.Count
       lcHttp = lcHttp + loCol.Item(lnX)
   ENDFOR
ELSE    	
   lcHttp = lcHttp + lcResponse
ENDIF

IF THIS.oServer.lComObject
  *** Assign text output direct to Server output
  THIS.oServer.cOutput= lcHttp                     && can be >16mb
ELSE
  FILE2VAR(this.oRequest.GetOutputFile(),lcHttp)   && can be >16mb
ENDIF

Every request in Web Connection runs through this method so this single point of output and so any large output can be chunked.

This uses a new helper function called SplitStringBySize():

************************************************************************
*  SplitStringBySize
****************************************
***  Function: Splits a string into a collection based on size
***    Assume: Useful for breaking 16mb strings
***      Pass: lcString  - string to split
***            lnLength  - where to split
***    Return: Collection of strings or empty collection
************************************************************************
FUNCTION SplitStringBySize(lcString, lnLength)
LOCAL lnTotalLength, lnStart, lnEnd, loCollection

lnTotalLength = LEN(lcString)
loCollection = CREATEOBJECT("Collection")

FOR lnStart = 1 TO lnTotalLength STEP lnLength
    lnEnd = MIN(lnStart + lnLength - 1, lnTotalLength)
    loCollection.ADD(SUBSTR(lcString, lnStart, lnEnd - lnStart + 1))
ENDFOR

RETURN loCollection
ENDFUNC
*   SplitString

As it turns out this works for:

Plain Response.Write() requests (ie. hand coded)
Response.ExpandScript() and Response.ExpandTemplate()
Any wwRestProcess handler

Use >16mb Content with Care

Turns out this is a very useful addition, even if I would highly recommend that you don't do this often! It's a bad idea to send huge amounts of data back to the client as it is slow to send/receive, and if you're sending JSON data or HTML table data it'll take forever to parse or render. It also puts a lot of memory pressure on the Visual FoxPro application, and may result in out of memory errors if output is too large and isn't immediately cleaning up.

Reducing Output Size Significantly with GZipCompression

Another thing that you can and should do if you are returning large amounts of text data is enable Response.GZipCompression = .T. either on the active request, or on all requests.

You can do this either in:

Process.OnProcessInit
this will be global and applied to every request in this process class. Add to the MyProcess::OnProcessInit() method.
Individual Process Method
this is specific to each individual method and applied only. Add to any Process method before the method completes.

Note that GZip compression only kicks in after output reaches a certain pre-configured size which is configured in wconnect.h and you can override it in wconnect_override.h:

#UNDEFINE GZIP_MIN_COMPRESSION_SIZE
#DEFINE GZIP_MIN_COMPRESSION_SIZE				15000

Anything smaller just gets returned un-encoded, while anything bigger gets GZipped.

Web Connection supports GZip compression of content with just that flag and especially for repeating content like JSON you can cut the size of a document immensely - typical between 5x and 10x smaller than the original size. Using GZipCompression gives you literally a ton more breathing room before you bump up against the 16mb limit.

In the testing I did a bit ago with a huge data set the data went from 18mb down to 2mb with GZipCompression. You get the benefit of a smaller memory footprint, plus vastly reduced transfer time of the data over the wire due to the smaller size.

##AD##

Summary

16mb for text or even JSON output should be avoid as much as possible. 16mb is a lot of data to either render, or parse as JSON data and I would not recommend doing that under most circumstances. But I know some of you will do it anyway, so this is why we're here ??

So, I've implemented this functionality in the current experimental update for Web Connection v8 so you can play with this right away.

Additionally you can also minimize the need for hitting the 16mb limit in many cases by using Response.GZipCompression = .t. which compresses the Response output. With typical HTML and JSON output, compression is significant with at least a 3x and as much as 10x reduction in output size in many instances. It's a very quick fix to reduce both the output size you're sending and keeping it under 16mb in the first place as well as reducing the network traffic and bandwidth usage significantly.

this post created and published with the Markdown Monster Editor

wwDotnetBridge Revisited: An updated look at FoxPro .NET Interop

Rick Strahl — Mon, 23 Sep 2024 07:34:21 GMT

by Rick Strahl
prepared for Southwest Fox 2024

Session Example Code on GitHub
Session Slides
wwDotnetBridge Repo on GitHub
wwDotnetBridge Docs
West Wind Message Board Support

.NET has proliferated as the dominant Windows development environment, both for Windows application development using a variety of different Windows-specific platforms and as the high-level API surface chosen by Microsoft to expose Windows system functionality besides low-level, native C++.

More importantly though, .NET has garnered a huge eco system of open source and commercial libraries and components that provide just about any kind of functionality and integration you can think of.

All of this is good news for FoxPro developers, as you can take advantage of most of that .NET functionality to extend your own FoxPro applications with rich functionality beyond FoxPro's native features using either basic COM interop (very limited) or more usefully with the open source wwDotnetBridge library.

##AD##

What we cover

.NET History: .NET Framework to .NET Core
.NET and FoxPro
Why .NET for FoxPro?
What is wwDotnetBridge?
A quick Primer
How does wwDotnetBridge Work
Working with .NET From FoxPro: Finding what you need!
- Figuring out what Assemblies (DLLs) to Provide
- Finding DLLs: Unpacking NuGet Packages and their Dependencies using a .NET Project
  - Use a Disassembler Tool to discover .NET Types and Members
  - Use LinqPad to Test Out Code
10 Usage Examples
1. wwDotnetBridge 101 â€“ Load, Create, Invoke, Get/Set
2. Create a powerful String Formatter
3. Add Markdown Parsing to your Applications
4. Use a Two-Factor Authenticator Library
5. Add Spellchecking to your applications
6. Humanize numbers, dates, measurements
7. A File System Watcher and Live Reload (Event Handling)
8. Async: Print Html to Pdf
9. Async: OpenAI Calls
  - Language Translation
  - Document Summary
  - Image Generation
10. Create a .NET Component and call it from FoxPro
Configuration and Application Management

.NET History: .NET Framework to .NET Core

.NET has been around since the early 2000's and in those nearly 25 years it has undergone a number of transformations. From its early days as a limited distributed runtime, to integration into Windows as a core Windows component, to the splitting off of .NET Core as a cross platform capable version of .NET, to full cross-platform support for .NET Core, to recent releases that provide nearly full compatibility with .NET Framework for .NET Core including of Windows specific platforms (ie. WinForms, WPF, WinUI).

The most significant change occurred in 2016, when .NET split off into the classic .NET Framework (the Windows native Runtime build into Windows) and .NET Core, which is a newly redesigned version of .NET that is fully cross-platform enabled and can run on Windows, Mac and Linux and that is optimized for performance and optimized resource usage. The new version has greatly expanded .NET's usefulness and developer reach with many new developers using the platform now.

This new version of .NET - although it had a rough initial start - is also mostly compatible with the classic .NET Framework and can for the most part run code on both frameworks interchangeably. .NET Core brought a ton of improvements to .NET in terms of performance and resource usage, as well as new server side frameworks (ASP.NET, Blazor, Maui etc.),and much simpler and universally available tooling that removed the requirement for developing applications exclusively on Windows using Visual Studio.

Today you can build applications for Windows, Mac or Linux, developing applications on these platforms using native editors either with integration tooling or command line tools that are freely available via the .NET SDK. The SDK includes all the compiler tools to build, run and publish .NET applications from the command line without any specific tooling requirements.

.NET and FoxPro

For FoxPro developers it's preferable to use components that use the old 'full framework' libraries when available even though .NET Core is the new and shiny new framework. The full .NET Framework (NetFX) is part of Windows and so it's always available - there's nothing else to install to run it and so it's the easiest integration path for FoxPro applications. For this reason I strongly recommend you use .NET Framework in lieu of .NET Core or .NET Standard components if possible.

However, it is possible to use .NET Core components with FoxPro and wwDotnetBridge. But the process of doing so tends to be more complicated as .NET Core's assembly loading is more complex, often requiring many more support assemblies that are not always easy to identify.

In order to use .NET Core you need to ensure a matching .NET Core runtime is installed to support the minimum version of any components you are calling. .NET Core goes back to requiring installable runtimes, rather than having a single system provided runtime as .NET Framework does. This means you have to ensure the right version of the runtime is installed. Although .NET Core also supports fully self contained installs, that's not really applicable to components or FoxPro applications, so we're always dependent on an installed runtime. Major Runtime Versions rev every year, the current version in late 2024 is v8 with v9 getting released in November.

The good news is that most components today still use multi-targeting and support both .NET Framework (or .NET Standard which is .NET Framework compatible) and .NET Core targeting and you can generally find .NET Framework components that work more easily in FoxPro.

Stick to .NET Framework

Bottom Line: If at all possible aim for using .NET Framework if you're calling .NET code from FoxPro. Only rely on .NET Core components if there is no alternative in .NET Framework available.

Why .NET for FoxPro?

.NET is a Microsoft platform and for better or for worse, it's the only platform that has good Windows support for desktop applications and that can be integrated relatively easily with Visual FoxPro, mainly because it works with COM.

FoxPro is very old technology, with the last released version now more than 15 years out of date, so in order to keep FoxPro applications up to date with current functionality some technology is needed to extend FoxPro beyond it's old feature set. The original extension technology was COM, but COM has died a slow death right alongside FoxPro, especially for high level languages that use IDispatch interface as FoxPro does. You'll be hard pressed to find a 'new' COM component that exposes business or system functionality these days. While COM is still heavily used internally in Windows with C++ code, most of the system functionality exposed to developers these days is exposed via .NET.

Further, these days it's fairly easy to get started building your own .NET components, which facilitates the ability to access more complex .NET code using your own .NET code that acts as a front end for the more complex .NET code.

This opens up many avenues of extensibility, both in terms of .NET component feature availability to your application, but also as an avenue for extensibility of your application using an alternate technology. What's nice about using a component based interface like this is that you ease into building functionality selectively in .NET and expose it from FoxPro. It's a great way to experiment with .NET for real world scenarios starting with small components, to potentially larger integrations down the road or even entire switching to a .NET based application eventually with the ability to use the code you've built along the way.

Because .NET is now multi-platform and can run desktop, Web, API, Phone and IOT based applications, any components you build also can be used in all of those environments (assuming they are platform agnostic), so any investments you make in .NET components can be re-used in other .NET based interfaces or even other .NET integrations. So today you might be building an extension interface for your FoxPro desktop application, but tomorrow you may be using that same extension in a .NET Web API application.

In short, for FoxPro developers .NET offers a path to extensibility via COM integration, that lets you take advantage of most of .NET's features with minimal effort.

Let's take a look at what that looks like.

What is wwDotnetBridge?

wwDotnetBridge is an open source, MIT licensed FoxPro library, that allows you to load and call most .NET components from FoxPro. It provides registrationless activation of .NET Components and helpers that facilitate accessing features that native COM Interop does not support.

.NET has built-in COM Interop support which allows you to instantiate and then invoke .NET objects via COM. Unfortunately this mechanism is very limited due to the requirement that components are registered in a special way to both COM and .NET, and that components have to be explicitly marked. Effectively this means you can only instantiate COM components that you have created your self.

To work around this wwDotnetBridge provides many improvements that work around the limitations of native .NET COM Interop, while still using COM Interop for the inter-process communication. Everything that works with native COM Interop also works with wwDotnetBridge - it's the same technology after all - but you get many more support features to work around the limitations.

The key features of wwDotnetBridge are:

Registrationless access to most .NET Components
Unlike native COM Interop, you can instantiate and access .NET Components and static classes, without requiring those classes to be registered as COM objects. Objects are instantiated from within .NET, so you can access most .NET components by directly loading them from their DLL assembly. Both .NET Framework (wwDotnetBridge) and .NET Core (wwDotnetCoreBridge) are supported.
Instantiates and Interacts with .NET Objects via COM from within .NET
wwDotnetBridge is a .NET based component that runs inside of .NET and acts as an intermediary for activation, invocation and access operations. A key feature is that it creates .NET instances from within .NET and returns those references using COM Interop. Once loaded you can use all features that COM supports directly: Property access and method calls etc. as long the members accessed use types that are supported by COM.
Support for Advanced .NET Features that COM Interop doesn't support
Unfortunately there are many .NET features that COM and FoxPro don't natively support directly: Anything related to .NET Generics, overloaded methods, value types, enums, various number types to name just a few. But because wwDotnetBridge runs inside of .NET, it provides automatic conversions and helpers to allow access to these features via intermediary Reflection operations. These helpers access the unsupported COM operations from inside of .NET and translate the results into COM and FoxPro compatible results that are returned into your FoxPro application.
Automatic Type Conversions
Because there are many incompatible types in .NET that don't have equivalents in COM or FoxPro, wwDotnetBridge performs many automatic type conversions. These make it easier to call methods or retrieve values from .NET by automatically converting compatible types. For example: decimals to double, long, byte to int, Guid to string etc. There are also wrapper classes like ComArray that wraps .NET Arrays and Collections and provides a FoxPro friendly interface for navigating and updating collections, and ComValue which wraps incompatible .NET values and provides convenient methods to set and retrieve the value in a FoxPro friendly way and pass it to .NET methods or property assignments.
Support for Async Code Execution
A lot of modern .NET Code uses async functionality via Task based interfaces, and wwDotnetBridge includes a InvokeTaskMethodAsyc() helper that lets you call these async methods and receive results via Callbacks asynchronously. You can also run any .NET synchronous method and call it asynchronously using InvokeMethodAsync() using the same Callback mechanism. Finally there's also support for handling .NET events with similar callback mechanics.

There's much more, but these are the most common features used in wwDotnetBridge.

##AD##

A quick Primer

Before we jump in with more explanations lets walk through a simple example that shows how to use wwDotnetBridge in a simple yet common scenario.

I'm going to use a pre-built sample component from a library that's part of the samples called wwDotnetBridgeDemo.dll which is one of the simplest things and also very common things we can do.

Setting up wwDotnetBridge

The first step is that you need wwDotnetBridge. wwDotnetBridge comes in two versions:

Free Open Source Version
This version is available for free with source code from GitHub. You can go to the repo and copy the files out of the /Distribution folder. Copy these files into your FoxPro application path.
uses CrlLoader.dll as the Win32 connector
Commercial Version in Web Connection and West Wind Client Tools
This version of wwDotnetBridge includes a few additional convenience features and .NET components that are not provided in free version. The core feature set however is identical. Unlike the open source version this version uses wwIPstuff.dll as the loader.
uses wwIPstuff.dll as the Win32 connector

The three files you need for wwDotnetBridge are:

CrlLoader.dll (OSS) or wwIPstuff.dll (Commercial)
wwDotnetBridge.dll
wwDotnetBridge.prg

Copy these into your root project folder. CrlLoader.dll or wwIPstuff.dll have to live in the root folder the other two can live along your FoxPro path.

Loading DLLs from Network Locations: Configuration required

.NET components require explicit configuration in order to support remote loading from network locations. This is done by creating a configuration file for your application yourapp.exe.config or the VFP IDE vfp9.exe.config, in their respective startup folders. We recommend at minimum you use the following .config file settings:
<?xml version="1.0"?>
<configuration>
  <runtime>
      <loadFromRemoteSources enabled="true"/>
  </runtime>
</configuration>

For all examples in this article I use the GitHub repo's root folder as my base directory from which to run the samples. There's a .\bin folder that contains all .NET assemblies and for this sample I'll use the bin\wwDotnetBridgeDemos.dll assembly.

I'll start with the entire bit of code and we'll break it down afterwards:

*** Set Environment - path to .\bin and .\classes folder
DO _STARTUP.prg

*** Load wwDotnetBridge
do wwDotNetBridge                 && Load library
LOCAL loBridge as wwDotNetBridge  && for Intellisense
loBridge = GetwwDotnetBridge()    && instance

*** Load an Assembly
? loBridge.LoadAssembly("wwDotnetBridgeDemos.dll")

*** Create an class Instance
loPerson = loBridge.CreateInstance("wwDotnetBridgeDemos.Person")

*** Access simple Properties - plain COM
? loPerson.Name
? loPerson.Company
? loPerson.Entered

*** Call a Method
? loPerson.ToString()
? loPerson.AddAddress("1 Main","Fairville","CA","12345")

*** Special Properties - returns a ComArray instance
loAddresses = loBridge.GetProperty("Addresses")  
? loAddresses.Count     && Number of items in array
loAddress = loAddresses.Item(0)
? loAddress.Street
? loAddress.ToString()

Loading wwDotnetBridge and Loading your first .NET Library

The first step is to load the FoxPro wwDotnetBridge class:

do wwDotNetBridge                 && Load library
LOCAL loBridge as wwDotNetBridge  && for Intellisense
loBridge = GetwwDotnetBridge()    && instance

The first line loads the library into FoxPro's procedure stack so that they library is available. Typically you'd do this at the top of your application once. The LOCAL declaration is optional and only done for Intellisense.

GetwwDotnetBridge() is a helper function that creates a cached instance of wwDotnetBridge that stays loaded even if loBridge goes out of scope. This is to minimize the overhead of having to reload or check to reload the .NET Runtime.

Loading Assemblies and Creating an Instance

Next you want to load an assembly (a DLL) which loads the functionality of that library and makes it accessible so that we can access functionality in it.

*** Load a .NET Assembly
if !loBridge.LoadAssembly("wwDotnetBridgeDemos.dll") 
   ? "ERROR: " + loBridge.cErrorMsg
   RETURN
endif

LoadAssembly is used to load a DLL from the current folder or any folder in your FoxPro path. LoadAssembly returns .T. or .F. and you can check the .cErrorMsg for more information if an error occurs.

Once the assembly is loaded you can create object within it. In this case I want to create a Person class:

*** Create an class Instance
loPerson = loBridge.CreateInstance("wwDotnetBridgeDemos.Person")
IF VARTYPE(loPerson) # "O"
   ? "ERROR: " + loBridge.cErrorMsg
   RETURN
ENDIF

The .CreateInstance() method takes a fully qualified type name which corresponds to the .NET namespace.classname (case sensitive). A namespace is an identifier that's use to separate types with the same name from each other so that if two vendors have components with the same name, they are still separated by their namespaces.

Again you can check for errors of the instance creation with a non-object type and you can use .cErrorMsg to get more information on the error.

Common errors for both of these methods are:

Invalid Names - including case. Make sure you name things EXACTLY
Missing dependencies (more on that later)

Direct Invocation of Members

If the class was created you have now received back a .NET Component in the form of a COM object and you can access any properties and methods that have simple types directly. Essentially any properties and methods that contain COM compatible types can be accessed directly.

So all of the following works:

*** Access simple Properties - plain COM
? loPerson.Name
? loPerson.Company
? loPerson.Entered

loPerson.Name = "Jane Doe"
loPerson.Company = "Team Doenut"
loPerson.Entered = DateTime()

Likewise you can call simple methods:

loPerson.ToString()
? loPerson.AddAddress("1 Main","Fairville","CA","12345")

because all of these operations work with simple types they just work with direct access to the .NET object. You can directly call the methods and access properties without any special fix up or proxying.

Proxy Invocation for Problem Types and Helpers

While simple types work just fine for direct access, .NET has many more types that are not compatible with COM or FoxPro types and can't be converted. This means direct access is simply not possible.

wwDotnetBridge provides a host of helper functions that effectively proxy indirect access to .NET functionality by translating data coming from FoxPro into .NET and vice versa. By hosting this proxy code inside of .NET, the proxy can access all features of .NET and - as best as possible - translate between the .NET and FoxPro incompatibilities.

In the example above, the loPerson.Addresses property is an array, a .NET collection type. Collection types and especially generic lists and dictionaries (List<T> or Dictionary<TKey, TValue> ) are very common in .NET for example. However, FoxPro and COM don't support Generics at all, and even basic arrays and lists are not well supported via COM interop. In addition, Value types, Enums or accessing any static members is not supported, but can be accomplished via wwDotnetBridge helpers.

So loPerson.Addresses is an array of address objects, so rather than directly accessing it via:

loAddress = loPerson.Addresses[1]; && doesn't work

you have to indirectly access the address array which returns a ComArray helper:

loAddresses = loBridge.GetProperty(loPerson,"Addresses");
lnCount = loAddresses.Count
loAddress = loAddress.Item(0);
? loAddress.Street
? loAddress.ToString()

GetProperty() is one of the most common helper methods along with InvokeMethod() and SetProperty(). Use these methods when direct access does not work or when you know you're dealing with types that don't work via FoxPro or COM.

These methods use Reflection in .NET to perform their task and you specify an base instance that the operation is applied to (ie. loPerson) and a Member that is executed as a string (ie. "Addresses").

Here's what InvokeMethod looks like:

lcName = "Rick"
loPerson.InvokeMethod(loPerson,"DifficultMethod", lcName)

There are also methods to invoke static members:

? loBridge.InvokeStaticMethod("System.String","Format", "Hello {0}", lcName)

There are many more helpers in the class and we'll see more of them in the examples in the later part of this article.

##AD##

How does wwDotnetBridge Work

wwDotnetBridge acts as an intermediary between FoxPro and .NET. In a nutshell, wwDotnetBridge is a loader for the .NET framework, and a proxy interface for FoxPro which allows FoxPro code to pass instructions into .NET code when native direct access to components is not supported. You get the best of both worlds: Native direct COM access when possible, and proxied indirect execution that translates between .NET and COM/FoxPro types to access features that otherwise wouldn't be available.

Here's a rough outline of how wwDotnetBridge loads and calls a .NET component:

A .NET Loader

The most important feature of wwDotnetBridge is that it acts as a loader that makes it possible to access most .NET types - including static members - from FoxPro. There's no registration required as wwDotnetBridge loads components from within .NET and passes them back to FoxPro.

wwDotnetBridge works like this:

It loads the .NET Runtime into the FoxPro Process (one time)
It bootstraps a .NET wwDotnetBridge.dll from the loader (one time)
wwDotnetBridge is the FoxPro ? .NET proxy interface (one time)
The loaded proxy instance is passed back to FoxPro (one time)
The FoxPro instance is then used to:
- Load .NET Assemblies (dlls) (once per library)
- Instantiate .NET Types
- Access 'simple' properties and methods directly via COM
- Invoke problem Methods and access problem Properties via indirect execution
- Convert specialty types that COM doesn't work with directly via specialty helpers

Figure 1 show what this looks like in a diagram:

Figure 1 - wwDotnetBridge: Loading a component, creating an instance and accessing members repeatedly

Let's break down the parts:

In order to execute .NET code from FoxPro, the .NET Runtime needs to be loaded into your FoxPro executable or the FoxPro IDE.

There are a couple of ways this can be done:

Native COM Interop via COM Instantiation
.NET has native support for COM instantiation, but it requires that .NET Components are explicitly marked for COM execution which very few are. COM components that you create yourself also have to be marked with explicit COM Interface markers, and have to be registered using a special .NET COM Registration tool. It works, but it's very limited.
not recommended any longer
wwDotnetBridge .NET Runtime Hosting
wwDotnetBridge includes a small Win32 API loader that bootstraps the .NET Runtime and loads itself into this runtime as the host loader assembly. This is similar to the way native COM Interop hosts the runtime, but it bootstraps the wwDotnetBridge .NET component that can directly instantiate .NET types without requiring COM registration or any special marker interfaces/attributes.

wwDotnetBridge Loader

The wwDotnetBridge is comprised of three components:

A Win32 native C++ Loader that loads the .NET Runtime
The wwDotnetBridge .NET Proxy class that acts as the bridge interface
The wwDotnetBridge FoxPro class that calls into the .NET Class to create classes, invoke methods and set/get properties etc.

The FoxPro class kicks off the process by instantiating the wwDotnetBridge FoxPro class which internally calls into the Win32 code to check and see whether the .NET Runtime is already running and if not starts it up and bootstraps the wwDotnetBridge .NET class into it. A reference to the .NET Class instance is then marshalled back into FoxPro over COM. The FoxPro class caches this COM references and can now make calls into the .NET Interface.

Once loaded the wwDotnetBridge FoxPro class can then communicate with the .NET class by loading assemblies, creating instances and accessing members - in essence it now has full access to the features of the wwDotnetBridge .NET interface.

Direct Member Access is via COM

Behind the scenes .NET Interop relies on COM to instantiate types. Both native COM interop and wwDotnetBridge instantiate or access .NET types and those types return their results over COM. Every call that is made to create an instance, access a method or set or get a property happens over COM regardless of whether you use direct access of objects, or you use wwDotnetBridge's helpers.

Direct COM access is obviously easiest and most efficient from FoxPro and it works with types that are supported by both COM and FoxPro. It works just like you'd expect: You can call methods and access properties directly on the object instance or use the value as is. This works for all 'basic' types, strings, integers, floats, dates, bool values etc. and as long as methods only pass and return these compatible types or properties you can directly access them. Easy!

Indirect Member Access via InvokeMethod(), GetProperty() and SetProperty()

But... .NET has a rich type system and certain types and operations don't translate to matching COM or FoxPro types. For example, you can't access static members via COM but you can with wwDotnetBridge. For problem type access wwDotnetBridge automatically provides translations for many types so that they can be used from FoxPro. For example long and byte are converted to ints, Guid is converted to string, DbNull (a COM null) is converted to null and so on.

For these 'problem' scenarios wwDotnetBridge supports indirect invocation which executes operations through the wwDotnetBridge .NET Component, which proxies the method call or property access from within .NET. Because the code executes within .NET it can use all of .NET's features to access functionality and then translate results in a way that COM and FoxPro supports.

The most commonly used methods are:

InvokeMethod() - Invokes a method on an object
GetProperty() and SetProperty() - Gets or sets a property on an object
InvokeStaticMethod() - call a static method by name
SetProperty() and GetStaticProperty() - gets or sets a static property by name

These methods automatically translate inbound and outbound parameters so that they work correctly in .NET and FoxPro.

wwDotnetBridge Proxy Type Wrappers: ComArray and ComValue

wwDotnetBridge provides wrapper types like ComArray and ComValue that automatically wrap types that are not directly supported via COM. ComArray is automatically returned for .NET Arrays, Lists and Collections and it provides the ability to access list items (via Items(n)) and the ability manipulate the list by adding, editing and removing items without the collection ever leaving .NET. Many collection types - especially Generic Ones - cause errors if any member is accessed at all, and so leaving the type in .NET makes it possible to manipulate it and still pass it to methods or assign it to a property.

ComValue is similar, and it provides a mechanisms for storing a .NET value with helper methods that convert to and from FoxPro types to extract and set the .NET stored value.

Both ComValue and ComArray can be passed to the indirect calling methods, and are automatically translated into their underlying types when passed. So if a method requires a List<T> parameter, you can pass a ComArray and InvokeMethod() fixes up the ComArray into the required List<T> typed parameter.

These features and helpers make it possible to access most of .NET's functionality from FoxPro.

##AD##

Working with .NET From FoxPro: Finding what you need!

One of the biggest hurdles to using .NET from FoxPro is that you have to figure out what's available, which components you need and what you can call in a .NET component.

Let's look at these 3 scenarios:

How do I get the DLLs I need
What dependencies are there
What methods and properties are there to access

Figuring out what Assemblies (DLLs) to Provide

First and foremost you need to figure out what components you want to use. There are typically three kinds:

Built-in .NET Framework components (built-in)
Third Party libraries provided as binary files (dlls)
Third Party or Microsoft Components that are distributed as NuGet packages (NuGet Packages ? dlls)

Raw DLL Distribution

In the old days of .NET there were only DLLs. Everything was either in the GAC, or distributed as a DLL that was attached as a reference to a project. That still works even in modern .NET although raw DLL usage tends to be rare these days as most components are shared as NuGet packages.

Built-in .NET Components that are part of the core framework are easiest as they are built into the .NET framework or they are located in the Global Assembly Cache. Most of these components are pre-loaded as part of the runtime, so you don't even need to call .LoadAssembly() to first load an assembly. Those that aren't pre-loaded can just be referenced by their assembly name.

This is obviously easiest because you don't really have to figure out where the DLLs are coming from. To figure out where runtime files live you can look at the .NET documentation - for a specific class. Each class tells you which namespace and the DLL file name.

The next option is to provide the Dll files for you to use. This is not very common any more as NuGet has taken over that space, but it's still relevant especially when you build your own .NET Components and distribute them. When you build your own components you generally build them into a DLL and then either build directly into the folder where they are needed or you copy them over to that location. At that point you just use .LoadAssembly() and you're on your way.

NuGet Package Distribution

These days the most common way .NET components are distributed is via NuGet packages - and for good reason. By publishing a component as a package an author can make that package available on the NuGet site and the component can be easily shared and accessed by millions of .NET developers as any component shows up in the NuGet package directory.

NuGet Packages are Zip files with .nupkg extension, that contain the published package Dlls, potentially for multiple .NET target platforms (ie. net472, net8.0). But the NuGet package Zip file does not contain any of its dependencies. Instead dependencies are resolved and unpacked as part of the .NET Build process using either dotnet build or dotnet restore in the SDK.

FoxPro doesn't have NuGet support, so we have to first manually 'unpack' NuGet packages and their dependencies in a way that we can capture all the required DLLs including the dependencies and add them to our own projects.

Make sure Dependencies are provided

It's crucially important that when you reference an assembly (dll) that all of its dependencies - and the right versions thereof - are also available in the same location or the app's root folder. The .NET loader has to be able to find the dependencies.

To give you an idea of a dependency graph, here's an example we'll use later on Westwind.Ai which talks to OpenAI services:

Figure 2 - NuGet packages can have dependencies that need to be available in order for a component to work.

Notice that this Westwind.AI package has a dependency on Westwind.Utilities which in turn has a dependency on Newtonsoft.Json. All three of these are required to load the component - miss one and the component won't load or break later at runtime when the relevant library is used. Make sure you have all of the dependencies available.

Note that many .NET packages don't have external dependencies, and in that case you can actually unzip and grab the DLLs directly. Just be sure that no other dependencies are required as it's often hard to debug assembly load errors after the fact only to find out you're missing a nested assembly.

Finding DLLs: Unpacking NuGet Packages and their Dependencies using a .NET Project

If you have a NuGet package and you want to 'unpack' it and all of its dependencies there's a 'proper' way of doing it to ensure you capture all dependencies. To resolve all of these dependencies into DLLs we can actually use with wwDotnetBridge in FoxPro, I recommend that you install the .NET SDK and build a tiny project that loads the NuGet package. That creates build output, along with all the dependent DLLs that you can then copy into your FoxPro project folder.

The SDK is a one time, low impact install and it's required in order to build .NET code.

To do this:

Create a new Console project by copying .csproj and program.cs files
Add a package reference to the desired component
Run dotnet build
Go to the /bin/Release/net472 folder
Pick up the DLLs and copy to your application
Or: reference DLLs in that folder

I use a Console project because it's most lightweight top level executable project you can build.

The project file can be totally generic so lets do it just by creating a couple of files:

Create a folder name it ConsoleTest
Create a file called ConsoleTest.csproj
Create a file called program.cs
Run dotnet build from that folder

Here's the content of these files. The .csproj project file looks like this:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net472</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Westwind.AI" Version="*" />    
    <!--<PackageReference Include="GoogleAuthenticator" Version="*" />-->
    <!--<PackageReference Include="WeCantSpell.Hunspell" Version="*" />-->
  </ItemGroup>
</Project>

Put the file into its own folder like ConsoleTest and name the project ConsoleTest.csproj.

Also create a file called program.cs file as the main program:

using System;

namespace ConsoleStart {
    public class Program 
    {
        public static void Main(string[] args) {
            Console.WriteLine("Hello World!");
        }
    }
}

dotnet new doesn't work for .NET Framework Projects

The SDK has built-in tools to create projects using dotnet new console -n ConsoleTest, but unfortunately newer SDK versions no longer support .NET Framework, even though it does support compilation of .NET Framework code. The problem is that new project types include a number of C# language features that are not supported in .NET Framework, so rather than removing and changing settings, it's simply easier to create or copy the files manually as shown above.

You can find the above template in the /dotnet/New Project net472 Template. To create a new project, copy the folder and rename the folder and project name and you're ready to go.

With these files in place and the .NET SDK installed, open a Terminal window in the ConsoleTest folder and run:

dotnet build

Output gets generated into the ./bin/Debug/net472 folder. Here's what that looks like using Visual Studio Code as the editor with its built-in Terminal (note: you can use whatever editor you like).

Figure 3 - Building a tiny .NET project with the NuGet package you want to use, produces all DLLs and dependencies you can copy into your own project.

As you can see the output compilation folder contains all 3 of the assemblies from the 3 NuGet packages and you can now copy those DLLs into your application folder.

You can create this project once, and simply add different package references into the project, delete the bin folder, then build again to figure out what dependencies you need to deploy:

Use a Disassembler Tool to discover .NET Types and Members

Once you have the DLLs and you can use them successfully with LoadAssembly() the next step is to find the types (classes) you want to load and the members you want to call on them.

There are many tools available that provide IL code inspection that can show you class hierarchies in a DLL:

ILSpy
JetBrain DotPeek
Reflector (old, free version included in .\tools)

Each tool is a little different, but most modern tools use live decompilation to show the class tree and member signatures. Figure 2 shows the Markdig Markdown library in ILSpy:

Figure 4 - Inspecting .NET Libraries for call signatures and class naming in ILSpy

There are a number of things to be aware of:

Classes are instantiated by using namespace.classname
All type names and members are case sensitive
All methods require exact parameter matches (default values are not supported over COM)
Overloaded methods cannot be called directly
If there are overloads make sure you use the exact parameter types

The above ToHtml() method - which happens to be a static method that doesn't require an objec instance - would be called like this from FoxPro:

loBridge = GetwwDotnetBridge()
loBridge.LoadAssembly("Markdig.dll")
lcHtml = loBridge.InvokeStaticMethod("Markdig.Markdown","ToHtml",lcMarkdown,null)

Use LinqPad to Test Out Code

Another extremely useful tool is LinqPad which you can think of as a Command Window for .NET. Like the FoxPro Command Window you can use LinqPad to test out code interactively. If you didn't create the component you're trying to access from .NET it's a good idea to try it out before you actually try to call it from FoxPro.

This is useful for several reasons:

Makes sure you are calling the code correctly, and it works in .NET
if it doesn't work in .NET, it sure as hell won't work in FoxPro!
Lets you check for type information interactively
hover over type declaration to see the namespace.classname and class
Lets you see overloads and test with different values/types
hover over a method and check for a drop down list (n overloads)

There are two versions of LinqPad available for different scenarios:

LinqPad 5.0 works with .NET Framework
LinqPad Latest (8.0 currently) works with .NET Core

Although in many cases both .NET Framework and Core work the same there are differences, so if you're testing for FoxPro you generally prefer using LinqPad 5.0 to test the .NET Framework versions of components.

Here's LinqPad checking out the Spell Checking example code:

Figure 5 - Using LinqPad to test out .NET functionality before creating FoxPro code.

LinqPad is an awesome tool if you're using .NET in general - it allows you to create small snippets for testing as I've shown, but you can also use it as a tool to create small utilities like converters, translators and general purpose tools that you can readily save and then later load. For example, I have several converters that convert TypeScript classes to C# and vice versa, de-dupe lists of email addresses and many other things that are basically stored as LinqPad scripts that I can pull up and tweak or paste different source text into.

Usage Examples

Ok enough theory - let's jump in and put all of this into practice with some useful examples that you can use in your own applications.

wwDotnetBridge 101 â€“ Load, Create, Invoke, Get/Set
Create a powerful String Formatter
Add Markdown Parsing to your Applications
Use a Two-Factor Authenticator Library
Add Spellchecking to your applications
Humanize numbers, dates, measurements
File Watcher and Live Reload (Event Handling)
Async: Use OpenAI for common AI Operations
Async: Print Html to Pdf
Create a .NET Component and call it from FoxPro

wwDotnetBridge 101 â€“ Load, Create, Invoke, Get/Set

Demonstrates:

Basics of wwDotnetBridge
Loading the library
Loading assemblies
Creating instances
Accessing members
Using special unsupported types

Lets start with a basic usage example that demonstrates how wwDotnetBridge works.

For this 101 level example I'm going to use a custom class in custom compiled project I created for examples for this session. We'll talk about how to create this class later, but for now just know that this project creates an external .NET assembly (.dll) from which we'll load a .NET class, and call some of its members.

Specifically we'll look at how to:

Load wwDotnetBridge
Load an Assembly
Create a .NET Object instance
Make native COM calls on the instance
Invoke or access problem members on an instance
Use Helper Classes to work with problematic .NET Types

Simple Invocation

The easiest way to look at this is to look at commented example.

do wwDotNetBridge                 && Load library
LOCAL loBridge as wwDotNetBridge  && for Intellisense only
loBridge = GetwwDotnetBridge()    && Create Cached Instance of wwDotnetBridge

*** Load an .NET Assembly (dll)
loBridge.LoadAssembly("wwDotnetBridgeDemos.dll")

*** Create a class Instance - `Namespace.Classname`
loPerson = loBridge.CreateInstance("wwDotnetBridgeDemos.Person")

*** Access simple Properties - direct access
? "*** Simple Properties:" 
? loPerson.Name
? loPerson.Company
? loPerson.Entered
?

*** Call a Method - direct access
? "*** Method call: Formatted Person Record (ToString):"
? loPerson.ToString()  && Formatted Person with Address
?

*** Add a new address - direct access
loAddress =  loPerson.AddAddress("1 Main","Fairville","CA","12345")

*** Special Properties - returns a ComArray instance
loAddresses = loBridge.GetProperty(loPerson, "Addresses")  

? loBridge.ToJson(loAddresses, .T.)  && Commercial only
? TRANSFORM(loAddresses.Count) + " Addresses"     && Number of items in array

? "*** First Address"
loAddress = loAddresses.Item(0)
? "Street: " + loAddress.Street
? "Full Address (ToString): " + CHR(13) + CHR(10) + loAddress.ToString()
? 

? "*** All Addresses"
FOR lnX = 0 TO loAddresses.Count-1
	loAddress = loAddresses.Item(lnX)
	? loAddress.ToString()
	?
ENDFOR

The first steps are pretty straight forward: You create an instance of the wwDotnetBridge object, which you then use to create an instance of a .NET class - or you can also call static methods directly (using .InvokeStaticMethod() more on that in the next sample).

Once you have the class you can call its methods and access its properties. For any properties and method signatures that are COM compliant, you can just directly access them the same way as you would for FoxPro members.

Indirect Execution

For problem types or some complex types likes arrays and collections, you have to use wwDotnetBridge's indirect invocation methods to access members. The three most common methods are:

InvokeMethod()
GetProperty()
SetProperty()

In this example, the loPerson instance includes an Addresses property which contains an array of Address object. While you can retrieve the Addresses object directly, you can't do anything useful with the array in FoxPro.

So rather than returning the array .GetProperty() returns you a ComArray instance instead which lets you access and manipulate the collection:

*** Returns a ComArray instance
loAddresses = loBridge.GetProperty(loPerson,"Addresses")

? loAddresses.Count   && 2
loAddress1 = loAddresses.Item(0)

FOR lnX = 0 to loAddresses.Count -1 
    loAddress = loAddresses.Item(lnX)
    * ? loAddress.Street
    ? loAddress.ToString()
ENDFOR

loNewAddress = loBridge.CreateInstance("wwDotnetBridge.Address")
loNewAddress.Street = "122 Newfound Landing"
loAddressses.Add(loNewAddress)

loAddresses.Count   && 3

Using ComArray for .NET Arrays, Lists and Collections

Because arrays and collections are ultra-common in .NET here's how you can add a new item to the collection using the same ComArray structure:

? "*** Add another item to the array"
* loNewAddress = loBridge.CreateInstance("wwDotnetBridgeDemos.Address")
loNewAddress = loAddresses.CreateItem()
loNewAddress.Street = "122 Newfound Landing"
loNewAddress.City = "NewFoundLanding"
loAddresses.Add(loNewAddress)

? TRANSFORM(loAddresses.Count) + " Addresses"  && 3
FOR lnX = 0 to loAddresses.Count -1 
    loAddress = loAddresses.Item(lnX)
    ? loAddress.ToString()
    ? 
ENDFOR

Summary

You've just seen how to:

Load a .NET Assembly
Create a .NET Class from within it
Call methods and set properties
Access a complex property and use a helper object
Work .NET Collections from FoxPro

Create a powerful String Formatter

Demonstrates:

Using .NET native String functions to format strings
Calling native .NET methods on objects without assembly loading
Invoking static methods
Creating simple wrapper functions for .NET functionality

This example is a little more practical: It makes most of .NET's string formatting features available to Visual FoxPro and exposes these as easy to use FoxPro functions. .NET has built-in string formatteing support that allow powerful formatting of things like dates and numbers along with C style string format templates.

In this example we'll access two native .NET features:

ToString()
This method is a base method on the lowest level .NET object which is System.Object and ToString() exists on every object and value in .NET except null. Each type can implement a custom implementation relevant to the type, or
System.String.FormatString()
Is a C-Style template string expansion method, that can be used to embed values more easily into strings using {n} value expansion. Additionally FormatString() supports the same format specifiers that ToString() supports on any templated values.

Formatting Dates and Numbers or any Formattable .NET Type with ToString()

The .NET System.Object base class exposes a ToString() method which ensures that every .NET object and value (except null) has a ToString() method, which allows you to write out any object as a string. Most common .NET types have practical ToString() implementations so that a number will write out the number as string, and date writes out in a common date format. More complex objects have custom ToString() implementations, and if you create your own classes you can override ToString() with your own string representation that makes sense.

Additionally ToString() supports an optional format specifier for many common types, which is specifically useful for numbers and dates since these can be represented in so many different ways.

ToString() with a format specifier is similar in behavior to Transform() in FoxPro, except that .NET formatters tend to be much more flexible with many more options.

The most common formatters are Date and Number formatters, but many other types also have formatters. To do this I'll implement a FormatValue() function in FoxPro shown after the examples.

Let's look at some Date formatting first:

.NET Date Format Strings Docs

do _startup.prg

do wwDotNetBridge
LOCAL loBridge as wwDotNetBridge
loBridge = GetwwDotnetBridge()

*** No Format String - Default ToString() behavior
? "Plain FormatValue on Date: "  + FormatValue(DATETIME())
* 6/6/2016 7:49:26 PM

lcFormat = "MMM d, yyyy"
? lcFormat + ": " +  FormatValue(DATETIME(),lcFormat)
* Jun 10, 2016

lcFormat = "MMMM d, yyyy"
? lcFormat + ": " + FormatValue(DATETIME(),lcFormat)
* August 1, 2016

lcFormat = "HH:mm:ss"
? lcFormat + ": " + FormatValue(DATETIME(),lcFormat)
* 20:15:10

cFormat = "h:m:s tt"
? lcFormat + ": " +  FormatValue(DATETIME(),lcFormat)
* 8:5:10 PM

lcFormat = "MMM d @ HH:mm"
? lcFormat + ": " +  FormatValue(DATETIME(),lcFormat)
* Aug 1 @ 20:44

lcFormat = "r"  && Mime Date Time
? lcFormat + ": " +  FormatValue(DATETIME(),lcFormat)
* Mon, 06 Jun 2016 22:41:33 GMT

lcFormat = "u"  
? lcFormat + ": " +  FormatValue(DATETIME(),lcFormat)
* 2016-06-06 22:41:44Z

lcFormat = "ddd, dd MMM yyyy HH:mm:ss zzz"
? "MimeDateTime: " +  STUFF(FormatValue(DATETIME(),lcFormat),30,1,"")
* 2016-06-06 22:41:44Z

There are a lot of different time formats available including fully spelled out versions. By default all date formats are in the currently active user locale (ie. en_US or de_DE) and the value will adjust based on which language you are running your application in. It's also possible to pass a specific .NET Culture to format for some other language and formatting, but that's not supported for the helpers discussed here.

Number formatting is very similar:

.NET Number Format Strings Docs

? "*** Numberformats"

*** Number formats

lcFormat = "00"  && fills with leading 0's
? lcFormat + ": " + FormatValue(2,"00")
* 02

? lcFormat + ": " + FormatValue(12,"00")
* 12

lcFormat = "c"    && currency (symbol, separator and default 2 decimals
? lcFormat + ": " +  FormatValue(1233.22,lcFormat)
* $1,233.22

lcFormat = "n2"   && separators and # of decimals
? lcFormat + ": " +  FormatValue(1233.2255,lcFormat)
* $1,233.23

lcFormat = "n0"   && separators and no decimals
? lcFormat + ": " +  FormatValue(1233.2255,lcFormat)
* $1,233
?

To implement the above FormatValue() function, I use a simple FoxPro wrapper function that looks like this:

************************************************************************
*  FormatValue
****************************************
***  Function: Formats a value using .NET ToString() formatting
***            for whatever the text ends up with
***      Pass:  Pass in any .NET value and call it's ToString()
***             method of the underlying type. This 
***             Optional FormatString ("n2", "MMM dd, yyyy" etc)
***    Return: Formatted string
************************************************************************
FUNCTION FormatValue(lvValue,lcFormatString)
LOCAL loBridge 

IF ISNULL(lvValue)
   RETURN "null"
ENDIF   

loBridge = GetwwDotnetBridge()

IF EMPTY(lcFormatString)	
	RETURN loBridge.InvokeMethod(lvValue,"ToString")
ENDIF  

RETURN loBridge.InvokeMethod(lvValue,"ToString",lcFormatString)
ENDFUNC
*   FormatValue

This function works off the value that we are passing into .NET and relies on the fact that .NET treats any value or object as an object. So a Date or Number, Boolean all are objects and we can call ToString(format) on those values. So it's literally a single method call.

If no parameter is passed we just call ToString() without parameters, otherwise we call ToString(format). Note that each overloaded .NET method requires a separate FoxPro call - even if the .NET method has default values for the method. This is because .NET internally looks at full method signatures and default parameter values are not part of the meta data that is used to match the right signature to call so we always have to call the exact signature that we want to use including potentially missing parameters. This can make translating C# code to FoxPro a little more tricky at times and is one of the reasons you should always verify method signatures in a Dissassembler tool like ILSpy or test methods in LinqPad with the full parameter structure.

We'll see this even more vividly in the FormatString() function we'll discuss next as it can take a variable number of parameters.

String Formatting with C Style String Templates

If you're old skool like me, you probably remember printf() from your C Computer Science classes back in the day. Most C style languages have printf() style string formatting functionality where you can 'inject' embeddable values into the string. This is not unlike FoxPro's TextMerge() function, but much more efficient and with the added benefit of the same string formatting available for embedded values as discussed for FormatValue().

Here's what this looks like when called from FoxPro:

? "*** String Formatting"
? FormatString("Hey {0}, the date and time is: {1:MMM dd, yyyy - h:mm tt}","Rick",DATETIME())
?

? "*** Brackets need to be double escaped"
? FormatString("This should escape {{braces}} and format the date: {0:MMM dd, yyyy}",DATE())

You can call FormatString() with a string 'template' that contains {0-n} expressions inside of it and you then pass parameters to the functions to fill in the {n} holes with the parameter values. The numbering is 0 based so you start with {0} for the first parameter.

Additionally you can also apply format strings as described in FormatValue() so you can use {0:MMM dd, yyy} for a Date expansion for example.

Note that FormatString() uses ToString() to format the value, so this works with any kind of object, although many actual objects don't implement it and instead return just the object name as Namespace.Classname.

However, if a class implements a custom ToString()method, it can do any kind of custom formatting - as I did in the wwDotnetBridge101 example and the Person.ToString() method, which outputs a full name and address block as a string:

// Person
public string DisplayName => (Name ?? string.Empty) +  
                             (!string.IsNullOrEmpty(Company) ?  $" ({Company})" : string.Empty);
                               
public override string ToString()
{
    return DisplayName + "\r\n" +                  
           Addresses.FirstOrDefault();  && .ToString() is implied! 
}

// Address
public override string ToString()
{
    return Street + "\r\n" + City + "\r\n" + State + " " + Zip;
}

You can then use that in FoxPro simply with:

*** Load loPerson .NET Object
? loBridge.LoadAssembly("wwDotnetBridgeDemos.dll")
loPerson = loBridge.CreateInstance("wwDotnetBridgeDemos.Person")
loPerson.Name = "Rick Strahl"
loAddresses = loBridge.GetProperty(loPerson,"Addresses")
loAddress = loAddresses.Item(0)
loAddress.City = "Anywhere USA"

*** Both of these work
? FormatValue(loPerson)
? loPerson.ToString()

The same also works with FormatString():

? FormatString("Person Object:\r\n{0} and the time is: {1:t}", loPerson, DATETIME())

FormatString() is very powerful and quite useful to quickly create string structures.

FormatString() also supports several C# string escape characters like \r \n and \t although that's not natively supported as .NET treats a foxPro string as is and escapes any special characters. However my implementation adds explicit support for \n\r\t\0 and escape them before passing to .NET (which has its own issue as you can't de-escape those values))

Here's what the FoxPro FormatString() function looks like:

************************************************************************
*  FormatString
****************************************
***  Function: Uses a string template to embed formatted values
***            into a string.
***    Assume:
***      Pass: lcFormat    -  Format string use {0} - {10} for parameters
***            lv1..lv10   -  Up to 10 parameters
***    Return:
************************************************************************
FUNCTION FormatString(lcFormat, lv1,lv2,lv3,lv4,lv5,lv6,lv7,lv8,lv9,lv10)
LOCAL lnParms, loBridge
lnParms = PCOUNT()
loBridge = GetwwDotnetBridge()

lcFormat = EscapeCSharpString(lcFormat)

DO CASE 
	CASE lnParms = 2
		RETURN loBridge.InvokeStaticMethod("System.String","Format",lcFormat,lv1)
	CASE lnParms = 3
		RETURN loBridge.InvokeStaticMethod("System.String","Format",lcFormat,lv1,lv2)
	CASE lnParms = 4
		RETURN loBridge.InvokeStaticMethod("System.String","Format",lcFormat,lv1,lv2,lv3)
	CASE lnParms = 5
		RETURN loBridge.InvokeStaticMethod("System.String","Format",lcFormat,lv1,lv2,lv3,lv4)
	CASE lnParms = 6
		RETURN loBridge.InvokeStaticMethod("System.String","Format",lcFormat,lv1,lv2,lv3,lv4,lv5)
	CASE lnParms = 7
		RETURN loBridge.InvokeStaticMethod("System.String","Format",lcFormat,lv1,lv2,lv3,lv4,lv5,lv6)
	CASE lnParms = 8
		RETURN loBridge.InvokeStaticMethod("System.String","Format",lcFormat,lv1,lv2,lv3,lv4,lv5,lv6,lv7)
	CASE lnParms = 9
		RETURN loBridge.InvokeStaticMethod("System.String","Format",lcFormat,lv1,lv2,lv3,lv4,lv5,lv6,lv7,lv8)
	CASE lnParms = 10
		RETURN loBridge.InvokeStaticMethod("System.String","Format",lcFormat,lv1,lv2,lv3,lv4,lv5,lv6,lv7,lv8,lv9)
	CASE lnParms = 11
		RETURN loBridge.InvokeStaticMethod("System.String","Format",lcFormat,lv1,lv2,lv3,lv4,lv5,lv6,lv7,lv8,lv10)
	OTHERWISE
	    ERROR "Too many parameters for FormatString"
ENDCASE

ENDFUNC
*   StringFormat

************************************************************************
*  EscapeCSharpString
****************************************
FUNCTION EscapeCSharpString(lcValue)

lcValue = STRTRAN(lcValue, "\r", CHR(13))
lcValue = STRTRAN(lcValue, "\n", CHR(10))
lcValue = STRTRAN(lcValue, "\t", CHR(9))
lcValue = STRTRAN(lcValue, "\0", CHR(0))

RETURN lcValue

The first thing you notice here's is that we are calling a static method on the System.String class. Static methods are non-instance method, meaning you don't first create an instance. Instead the methods are static and bound to a specific type ie. System.String. In FoxPro this is similar to a UDF() function or plain function that is globally available. Static methods and properties are referenced by the type name - ie. System.String instead of the instance, followed by the method or member name.

Here we call the static Format method with the format string and a single value as a parameter:

loBridge.InvokeStaticMethod("System.String","Format",lcFormat,lv1)

In this method, you'll notice the requirement to call each of the overloads for each parameter variation, which looks tedious but actually is the most efficient way to call this method. There are other overloads of InvokeStaticMethod() that can be passed an array of parameters, and while that would be cleaner to look at and allow for an unlimited number of parameters, it's less efficient as the array has to be created and parsed on both ends. Passing values directly is significantly faster, and for a low-level utility method like this, it's definitely beneficial to optimize performance as much as possible.

Summary

In this example you learned:

Calling native .NET Methods
Calling a non-instance Static method
How .NET Format Strings and ToString() work

Add Markdown Parsing to your Applications

Demonstrates:

Using a third party NuGet library
Calling static methods
Creating a FoxPro wrapper class to abstract functionality

The next example demonstrates using a Markdown to HTML parser. Markdown is a very useful text format that uses plain text mixed with a few readable text markup expressions that allow create rich HTML document text via plain text input. It can be used in lieu of WYIWYG editors and because it can be rendered very quickly allows you to actually preview content as you type in real time. So rather than typing in a simulated text editor to tries to simulate the final markup, you write plain text with markup simple expressions and look at a preview (or not) to see what the final output would look like.

In short it's a great tool for writing text that needs to be a little more fancy than just a wall of plain text. It's super easy to add bold, italic, lists, notes, code snippets, embed link and images using Markdown.

Some Examples of Markdown Usage

I'm a huge fan of Markdown and I've integrated it into several of my applications:

Markdown Monster (a Markdown Editor)

Help Builder (HTML documentation and HTML preview)
West Wind Message Board (used for message text)
My Weblog - posts are written in Markdown and rendered to HTML
Articles like this one - written in Markdown

Using Markdig for Markdown To HTML Conversion

Let's start with the simplest thing you can do which is to use a 3rd party library and it's most basic, default function to convert Markdown to Html which is sufficient for most use cases.

I'm using an older version of Markdig (v0.15.2) because it has no extra dependencies. Later versions work fine (although the ToHtml() method signature changes) but it requires that you add several additional dependencies of .NET assemblies. The old version has all the features you are likely to need so for FoxPro use this is the preferred version.

Notice that there are two parameters to the Markdig.Markdown.ToHtml() method: The markdown and a markdown parser pipeline that is optional. Remember from FoxPro we always have to pass optional parameters so we can pass the default value of null.

DO wwutils && For Html Preview

do wwDotNetBridge
LOCAL loBridge as wwDotNetBridge
loBridge = GetwwDotnetBridge()

loBridge.LoadAssembly("markdig.dll")

TEXT TO lcMarkdown NOSHOW
# Raw Markdown Sample using the Markdig Parser

This is some sample Markdown text. This text is **bold** and *italic*.

* [Source Code for this sample on GitHub](https://github.com/../markdownTest.PRG)

![](https://markdownmonster.west-wind.com/docs/images/logo.png) 

* List Item 1
* List Item 2
* List Item 3

Great it works!

> #### Examples are great
> This is a block quote with a header
ENDTEXT


***  Actual Markdown Conversion here - Invoke a Static Method
lcHtml = loBridge.InvokeStaticMethod("Markdig.Markdown","ToHtml",;
                                     lcMarkdown,null)

? lcHtml
ShowHtml(lcHtml)  && from wwUtils show in browser unformatted

And that works:

We have to load the markdig.dll library, but the key feature of this code is the static method call to:

lcHtml = loBridge.InvokeStaticMethod("Markdig.Markdown","ToHtml",;
                                     lcMarkdown,null)

This method takes the markdown to parse, plus a parameter of a ParserFactory which we have to pass even though the parameter is null. As I often do I first create the code I want to call in LinqPad to test, then call it from FoxPro. Here's the LinqPad test:

And that works.

Adding a more sophisticated Parser Wrapper

The call to ToHtml() in its default form with the parser pipeline set to null gets you a default parser, but you might want to take advantage of additional features of add-ons that the parser supports. For example, you can add support for Github Flavored Markdown (Github specific features), Grid Tables, Pipe Tables, automatic link expansion and much more.

To do this it's a good idea to create a wrapper class and build and cache the pipeline so it can be reused easily.

Here's a Markdown Parser class:

*************************************************************
DEFINE CLASS MarkDownParser AS Custom
*************************************************************
oPipeline = null
oBridge = null

lEncodeScriptBlocks = .T.
lSanitizeHtml = .T.
lNoHtmlAllowed = .F.

************************************************************************
FUNCTION Init()
****************************************
LOCAL loBridge as wwDotNetBridge

loBridge = GetwwDotnetBridge()

this.oBridge = loBridge
IF ISNULL(THIS.oBridge)
   RETURN .F.
ENDIF

IF !loBridge.LoadAssembly("markdig.dll")
   RETURN .F.
ENDIF   

ENDFUNC
*   Init

************************************************************************
FUNCTION CreateParser(llForce, llPragmaLines)
****************************************
LOCAL loBuilder, loValue, loBridge

IF llForce OR ISNULL(this.oPipeline)
	loBridge = this.oBridge
	loBuilder = loBridge.CreateInstance("Markdig.MarkdownPipelineBuilder")

	loValue = loBridge.Createcomvalue()
	loValue.SetEnum("Markdig.Extensions.EmphasisExtras.EmphasisExtraOptions.Default")	
	loBuilder = loBridge.Invokestaticmethod("Markdig.MarkdownExtensions","UseEmphasisExtras",loBuilder,loValue)

	loBuilder = loBridge.Invokestaticmethod("Markdig.MarkdownExtensions","UseListExtras",loBuilder)	
	loBuilder = loBridge.Invokestaticmethod("Markdig.MarkdownExtensions","UseCustomContainers",loBuilder)

	loBuilder = loBridge.Invokestaticmethod("Markdig.MarkdownExtensions","UseFooters",loBuilder)
	loBuilder = loBridge.Invokestaticmethod("Markdig.MarkdownExtensions","UseFigures",loBuilder)
	loBuilder = loBridge.Invokestaticmethod("Markdig.MarkdownExtensions","UseFootnotes",loBuilder)
	loBuilder = loBridge.Invokestaticmethod("Markdig.MarkdownExtensions","UseCitations",loBuilder)	
	
	loBuilder = loBridge.Invokestaticmethod("Markdig.MarkdownExtensions","UsePipeTables",loBuilder,null)
	loBuilder = loBridge.Invokestaticmethod("Markdig.MarkdownExtensions","UseGridTables",loBuilder)

	loValue = loBridge.Createcomvalue()
	loValue.SetEnum("Markdig.Extensions.AutoIdentifiers.AutoIdentifierOptions.GitHub")
	loBridge.Invokestaticmethod("Markdig.MarkdownExtensions","UseAutoIdentifiers",loBuilder,loValue)
	loBuilder = loBridge.Invokestaticmethod("Markdig.MarkdownExtensions","UseAutoLinks",loBuilder)
	
	loBuilder = loBridge.Invokestaticmethod("Markdig.MarkdownExtensions","UseYamlFrontMatter",loBuilder)
	loBuilder = loBridge.Invokestaticmethod("Markdig.MarkdownExtensions","UseEmojiAndSmiley",loBuilder,.T.)

	IF this.lNoHtmlAllowed
	   loBuilder = loBridge.Invokestaticmethod("Markdig.MarkdownExtensions","DisableHtml",loBuilder)
	ENDIF

	IF llPragmaLines
	  loBuiler = loBridge.Invokestaticmethod("Markdig.MarkdownExtensions","UsePragmaLines",loBuilder)
	ENDIF

	THIS.oPipeline = loBuilder.Build()
ENDIF

RETURN this.oPipeline
ENDFUNC
*   CreateParser

************************************************************************
FUNCTION Parse(lcMarkdown, llUtf8, llDontSanitizeHtml)
LOCAL lcHtml, loScriptTokens, loPipeline, lnOldCodePage

IF !this.lEncodeScriptBlocks
   loScriptTokens = TokenizeString(@lcMarkdown,"<%","%>","@@SCRIPT")
ENDIF

loPipeline = this.CreateParser()

*** result always comes back as UTF-8 encoded
IF (llUtf8)
   lnOldCodePage = SYS(3101)
   SYS(3101,65001)
   lcMarkdown = STRCONV(lcMarkdown,9)
ENDIF

lcHtml = this.oBridge.InvokeStaticMethod("Markdig.Markdown","ToHtml",lcMarkdown,loPipeline)

IF llUtf8
  SYS(3101,lnOldCodePage)  
ENDIF

IF !THIS.lEncodeScriptBlocks
  lcHtml = DetokenizeString(lcHtml,loScriptTokens,"@@SCRIPT")
ENDIF

IF PCOUNT() < 3
   llDontSanitizeHtml = !THIS.lSanitizeHtml
ENDIF   

IF !llDontSanitizeHtml
  lcHtml = THIS.SanitizeHtml(lcHtml)
ENDIF

lcHtml = TRIM(lcHtml,0," ",CHR(13),CHR(10),CHR(9))

RETURN lcHTML   
ENDFUNC
*   Parse


************************************************************************
*  SanitizeHtml
****************************************
***  Function: Removes scriptable code from HTML. 
************************************************************************
FUNCTION SanitizeHtml(lcHtml, lcHtmlTagBlacklist)

IF EMPTY(lcHtmlTagBlackList)
	lcHtmlTagBlackList = "script|iframe|object|embed|form"
ENDIF
IF EMPTY(lcHtml)
   RETURN lcHtml	
ENDIF

RETURN THIS.oBridge.InvokeStaticMethod("Westwind.WebConnection.StringUtils","SanitizeHtml",lcHtml, lcHtmlTagBlacklist)
ENDFUNC
*   SanitizeHtml

ENDDEFINE

The key method is the CreateParser() which explicitly adds the features that we want to use with the parser. There are additional methods that help with optionally cleaning up HTML for safe rendering by removing script code and frames and other things that could allow XSS attacks against the rendered HTML as Markdown allows embedded HTML in the Markdown text.

In the samples there's another sublass called MarkdownParserExtended that adds a few more features to the parser that include code snippet parsing, expanding FontAwesomeIcons and a few other things. You can look at the source code for more info.

With this code in place you can now just create another helper method that uses this parser and cache it so we don't have to reload the pipeline and instance for each invocation:

************************************************************************
*  Markdown
****************************************
***  Function: Converts Markdown to HTML
***    Assume: Caches instance in __MarkdownParser
***      Pass: lcMarkdown  - text to convert to HTML from Markdown
***            lnMode      - 0/.F. - standard, 2 extended, 1 - standard, leave scripts, 3 - extended leave scripts
***    Return: parsed HTML
************************************************************************
FUNCTION Markdown(lcMarkdown, lnMode, llReload, llUtf8, llNoSanitizeHtml, llNoHtmlAllowed)
LOCAL loMarkdown, lcClass

IF llReload OR VARTYPE(__MarkdownParser) != "O" 
	IF EMPTY(lnMode)
	   lnMode = 0
	ENDIF   

	lcClass = "MarkdownParser"
	IF lnMode = 2
	   lcClass = "MarkdownParserExtended"
	ENDIF
	
	loMarkdown = CREATEOBJECT(lcClass)
	PUBLIC __MarkdownParser
	__MarkdownParser = loMarkdown
	
	IF lnMode = 1 OR lnMode = 3
	   __MarkdownParser.lEncodeScriptBlocks = .F.  	  	   	  
	ENDIF	
	
	__MarkdownParser.lSanitizeHtml = !llNoSanitizeHtml
	__MarkdownParser.lNoHtmlAllowed = llNoHtmlAllowed
ELSE
    loMarkdown = __MarkdownParser
ENDIF

RETURN loMarkdown.Parse(lcMarkdown, llUtf8)
ENDFUNC
*   Markdown

Using Templates to make the Markdown Look Nicer

Markdown is useful especially in Web applications where HTML can be directly displayed inside of a Web Page. But if you just generate the HTML and display it as is the output is somewhat underwhelming as you're getting the browser's default styling.

If you're using Markdown in desktop applications what you'd want to do, likely is to create an HTML page template into which to render the generated HTML, with CSS styling applied so you can produce output that looks a little more user friendly:

This actually uses styling I picked up from Markdown Monster via templating. This works by creating an HTML template and embedding the rendered markdown - along with some base paths - into it:

Beware of FoxPro's TextMerge() Function

Initially I used the TextMerge() function to merge text, but it turns out that it has difficulty with linefeeds (/n) rather than CRLF, which are common with Markdown content created in external editors. For certain things like code snippets the stripped line breaks are causing problems. So rather than using TextMerge() in the code below I'm explicitly placeholder values in the text.

<!DOCTYPE html>
<html lang="en">
<head>
    <base href="${basePath}"/>
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
    <meta charset="utf-8"/>

    <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
    <link href="${themePath}..\Scripts\fontawesome\css\font-awesome.min.css" rel="stylesheet"/>
    <link href="${themePath}Theme.css" rel="stylesheet"/>

    <!-- All this is for Code Snippet expansion -->
    <script src="${themePath}..\Scripts\jquery.min.js"></script>
    <link href="${themePath}..\Scripts\highlightjs\styles\vs2015.css" rel="stylesheet"/>
    <script src="${themePath}..\Scripts\highlightjs\highlight.pack.js"></script>
    <script src="${themePath}..\Scripts\highlightjs-badge.js"></script>
    <script src="${themePath}..\Scripts\preview.js" id="PreviewScript"></script> 
</head>
<body>
  <!-- Optional header for the page -->   
  <div style="padding: 0.7em; background: #444; color: white; font-size: 0.8em">    
    <div style="float: right; color: goldenrod; font-weight: 600">    
      Southwest Fox Conference, 2024
    </div>
    <div>
      <img src="Assets/touch-icon.png" style="max-height: 1.3em; padding-right: 0.4em" />
      <span style="font-size: 1.35em; font-weight: 600; color: goldenrod; font-weight: 600">wwdotnetbridge Revisited</span> 
      <i style="font-size: 0.7em">by Rick Strahl</i>
    </div>    
  </div>

<div id="MainContent">

  <!-- Markdown Monster Content -->
  
  ${htmlContent}
  
  <!-- End Markdown Monster Content -->
</div>

</body> 
</html>

As you can see there are areas to be replaced with ${htmlContent} and ${basePath} and ${themePath} variables.

I then use a ShowWebPage.prg file to render the HTML into the template to get the desired styling and other feature support.

LPARAMETERS lcHTML, lcFile, lcThemePath

************************************************************************
* FUNCTION ShowWebPage
**********************
***  Function: Takes an HTML string and displays it in the default
***            browser. 
***    Assume: Uses a file to store HTML temporarily.
***            For this reason there may be concurrency issues
***            unless you change the file for each use
***      Pass: lcHTML       -   HTML to display
***            lcFile       -   Temporary File to use (Optional)
***            loWebBrowser -   Web Browser control ref (Optional)
************************************************************************
LOCAL lcBasePath, lcThemePath

lcHTML=IIF(EMPTY(lcHTML),"",lcHTML)
lcFile=IIF(EMPTY(lcFile),SYS(2023)+"\ww_HTMLView.htm",lcFile)
lcBasePath = ADDBS(SYS(5) + CURDIR())
lcThemePath = lcBasePath + "Assets\Westwind\"
lcTemplate = "./Assets/Westwind/Theme.html"

IF !EMPTY(lcTemplate)
   lcT =  FILETOSTR(lcTemplate)

   *** TextMerge does weird shit with LineBreaks so do explicit replacements	
   * lcMerged = TEXTMERGE(lcT)
   
   *** For some reason TEXTMERGE strips line feeds
   lcT = STRTRAN(lcT,"${basePath}", lcBasePath)
   lcT = STRTRAN(lcT,"${themePath}", lcThemePath)
   lcHtml = STRTRAN(lcT, "${htmlContent}", lcHtml)
ENDIF

*** Dump to file and preview in Browser
STRTOFILE(STRCONV(lcHtml,9),lcFile)
ShellExecute(lcFile)

RETURN


FUNCTION ShellExecute(tcUrl, tcAction, tcDirectory, tcParms, tnShowWindow)

IF VARTYPE(tnShowWindow) # "N"
   tnShowWindow = 1
ENDIF

IF EMPTY(tcUrl)
   RETURN -1
ENDIF
IF EMPTY(tcAction)
   tcAction = "OPEN"
ENDIF
IF EMPTY(tcDirectory)
   tcDirectory = SYS(2023) 
ENDIF

DECLARE INTEGER ShellExecute  ;
    IN SHELL32.dll as ShellExec_1;
    INTEGER nWinHandle,;
    STRING cOperation,;
    STRING cFileName,;
    STRING cParameters,;
    STRING cDirectory,;
    INTEGER nShowWindow
    
IF EMPTY(tcParms)
   tcParms = ""
ENDIF

RETURN ShellExec_1( _Screen.HWnd,;
                    tcAction,tcUrl,;
                    tcParms,tcDirectory,tnShowWindow)
ENDFUNC
*   ShellExecute

To use this now becomes pretty simple:

loParser = CREATEOBJECT("MarkdownParserExtended")

TEXT TO lcMarkdown NOSHOW
This is some sample Markdown text. This text is **bold** and *italic*.

* List Item 1
* List Item 2
* List Item 3

Great it works!

> #### <i class="fas fa-info-circle" style="font-size: 1.1em"></i>  Examples are great
> This is a block quote with a header


### Link Embedding is easy

* [Sample Repositor](https://github.com/RickStrahl/swfox2024-wwdotnetbridge-revisited)
* [Source Code for this sample on GitHub](https://github.com/RickStrahl/swfox2024-wwdotnetbridge-revisited/blob/master/markdownTest.PRG)

### Markdown Monster wants to eat your Markdown!

* [Download Markdown Monster](https://markdownmonster.west-wind.com)

![](https://markdownmonster.west-wind.com/Images/MarkdownMonsterLogo.jpg)

### The Markdown Editor for Windows

ENDTEXT

*** Render the page
lcHtml = loParser.Parse(lcMarkdown)
? lcHtml

*** 
ShowWebPage(lcHtml)

Note that this example is hacked together using the existing Markdown Monster templates, so it it needs a little work to render quite right, but the idea is this:

Set up a base HTML page
Text Merge any paths and related things into the page
Text Merge the rendered Html

Have a fully reusable HTML template that you can easily call to render consistent looking Markdown. This is essentially what I do in Markdown Monster, Help Builder (both desktop apps) as well as on my Weblogs - all use Markdown text rendered into a base template.

Markdown is an extremely powerful tool, and once you use it for a few things it becomes addicitive and you will loathe going back to a full editor like Word for most writing or documentation tasks.

Use a Two-Factor Authenticator Library

Demonstrates:

Use a third party library
Make simple direct COM calls
Very useful to create Two-Factor Auth for Web and Desktop apps
NuGet Library used: GoogleAuthenticator

Two factor authentication is a second level of security that you can use in addition to typical username/password or similar login style security both in Web and even in Desktop applications. Two-Factor auth serves a second unrelated safety mechanism to verify an account, which makes it much harder to hack an account even if passwords are compromised.

There are many mechanisms that can be used for two-factor auth including using SMS messages to verify a user, or using a separate email address. However, a somewhat newer approach uses Authenticator apps like Authy, Google Authenticator, Microsoft Authenticator, or password managers like 1Password, Lastpass etc. The Authenticator is used as a key generator that can then generate new one-time codes that can be checked. The two factor one time codes use a standard hashing mechanism that which means it works with any of the above mentioned tools. All of these apps and devices uses the same algorithms to set up and then validate two factor one time codes. Any of these apps or devices can be used as Authenticators, but once you create a two-factor setup you have to use the same app or device to validate the codes.

Two-Factor auth is fully self-contained which means there's no need to use a third party service or any special tools although you can use a hardware key as an option. Hardware keys provide their own fixed secret so you skip the typical QR/Setup code configuration and instead provide the secret key directly to be stored by the host application that will be validating the generated codes.

Two factor authentication is made of two specific steps:

Setting up Two-Factor Authentication
This involves creating a setup key from a unique application generated secret key. The secret key is used to configure the Two Factor app, and it's used to create the initial QR/Setup code. For setup the code is typically displayed as a QR Code that can be scanned with a phone or from a Web app (in desktop Web browser). Alternately this code is also displayed as a numeric key you can manually type into an authenticator or hardware device where QR codes are not supported. To generate a new two-factor setup you typically provide some unique secret identifier that is then later also used to validate two-factor codes.
Validating a One Time Passkey
Once a Two-Factor auth setup has been configured, you then need to validate it. To validate you ask the Authenticator app for a new two-factor one time code and you validate it in combination with your unique application level secret identifier. Based on the two-factor one time code and and the identifier the code can be validated as valid within a given time frame.

Here's what the sample looks like:

What I'm presenting here are the tools to do two-factor authentication, not an actual implementation as that's way too complex to tackle here. If you are interested in full two-factor implementation for a Web site see my post on Two-Factor authentication in a .NET Web application.

In a live application here's what this looks like.

QR Code Setup

As a user you can capture the QR code in an authenticator app like Authy here:

or, more conveniently as part of a password manager like 1Password as I do:

App presents a QR code to initially set up two factor authentication. This is a one time operation where the app generates a new secret key and then stores that secret key with the user/customer record to later use for validation.

Then when a user logs in, they first log in with their username and password, and then are immediately asked for the two-factor one time code as well.

And you can fill that in via your authenticator app, or as I do here with 1Password:

Two-Factor Auth with the GoogleAuthentor Library

Unlike the name suggests, this library is not limited to Google Authenticator. It works with any two-factor authenticator like Authy, Microsoft Authenticator and 1Password. The algorithm that is used for two-factor auth hashing is generic so it works with any tool that supports these protocols, but once set up the codes can only be generated by your configured Authenticator tool.

The code to use this library from FoxPro is very simple. The easiest way to use it is to create a small wrapper class:

*************************************************************
DEFINE CLASS TwoFactorAuthentication AS Custom
*************************************************************

oBridge = null
oAuth = null

************************************************************************
FUNCTION Init()
****************************************
this.oBridge = GetwwDotnetBridge()

IF (!this.oBridge.LoadAssembly("Google.Authenticator.dll"))
   ERROR this.oBridge.cErrorMsg
ENDIF  
THIS.oAuth = this.oBridge.CreateInstance("Google.Authenticator.TwoFactorAuthenticator")
IF VARTYPE(THIS.oAuth) # "O"
   ERROR "Failed to load TwoFactorAuthenticator: " + this.oBridge.cErrorMsg
ENDIF

ENDFUNC

*********************************************************************************
FUNCTION GenerateSetupCode(lcApplicationName, lcEmail, lcSecretKey, lnResolution)
****************************************
***  Function: Generates a structure that generates an object containing 
***            a QR code image and manual setup code
***    Assume: Application and Email have no effect on code/qr generation
***      Pass: lcApplicationName  - Name of application
***            lcEmail            - An email address to identify user
***            lcSecretKey        - Secret key tied to the user to identify
***            lnResolution       - larger numbers result in larger CR codes (10)
***    Return: TwoFactorSetup object or null
************************************************************************
LOCAL loAuth

IF EMPTY(lnResolution)
   lnResolution = 10
ENDIF   

loSetupInfo = THIS.oAuth.GenerateSetupCode(lcApplicationName,;
   lcEmail, ;
   lcSecretKey, ;
   .F., lnResolution)
   
loResult = CREATEOBJECT("TwoFactorSetup")
loResult.cQrCodeImageData = loSetupInfo.QrCodeSetupImageUrl
loResult.cSetupKey  = loSetupInfo.ManualEntryKey
loResult.cCustomerSecret = lcSecretKey

RETURN loResult
ENDFUNC

************************************************************************
FUNCTION ValidatePin(lcSecretKey, lcPin)
****************************************
lcPin = STRTRAN(lcPin, " " ,"")
RETURN THIS.oAuth.ValidateTwoFactorPIN(lcSecretKey, lcPin)
ENDFUNC

ENDDEFINE


*************************************************************
DEFINE CLASS TwoFactorSetup AS Custom
*************************************************************

*** Base64 Data Url that contains the image data 

cQrCodeImageData = ""


*** Typable Version of the QrCode data
cSetupKey = ""

*** Unique Customer Key - pass and save with your app
cCustomerSecret = ""

************************************************************************
FUNCTION QrCodeHtml(llImageOnly)
****************************************
IF (llImageOnly)
   RETURN [<img src="] + this.cQrCodeImageData + [" />]
ENDIF

TEXT TO lcHtml NOSHOW TEXTMERGE
<html>
<body>
<div style="text-align: center; max-width: 500px">
	<img src="<<this.cQrCodeImageData>>" />
	<div style="font-size: 1.5em; font-weight: 600">
	<<this.cSetupKey>>
	</div>
</div>
</body>
</html>
ENDTEXT

RETURN lcHtml
* QrCodeHtml

ENDDEFINE
*EOC TwoFactorSetup

The class only has two methods that wrap the basic behavior to create a new Two-Factor setup and to validate it.

Generating and Displaying a QR Setup Code

Let's start with how to generate and then display the QR Code:

*** For demo only (ShowHtml()/InputForm()/GetUniqueId())
DO wwutils

*** Generate a Customer Secret key 
*** In an application this will be something that identifies the user
*** with a given account, but it needs to be something that is not known
*** typically a generated UniqueId stored in a customer record (TwoFactorKey in db for example)
lcSecret = GetUniqueId(12)    

loAuth = CREATEOBJECT("TwoFactorAuthentication")
loSetup  = loAuth.GenerateSetupCode("Westwind.Webstore",;
                                    "rick@test-my-site.com", lcSecret)

ShowHtml( loSetup.QrCodeHtml())

Yeah pretty simple, eh? To start you need some sort of unique ID that you need to store with your application once the two-factor authentication has been enabled. This key is the shared secret between you and the authenticator and it's needed to validate two-factor codes. Ideally you want a random value for this and store it as a separate field in your user or customer database that identifies a user.

You call GenerateSetupCode() to generate the QrCode or manual setup code which are used initialize the Authenticator for your app.

The method returns an loSetup structure that contains the cQrCodeImageData which is HTML base64 encoded image data that can be directly assigned to an <img src="" /> attribute. We can take advantage of that to display the QR code quite easily in an HTML page as shown in the initial examples.

The Setup class includes a mechanism to render the image as HTML into a page that can be displayed:

You can see the image tag:

<img src="data:image/png;base64,<longBase64Text>"  />

Alternately if you want to capture the actual image data you can parse the encoded cQrCodeImageData, extract the base64 text and use STRCONV() to turn that into binary data that you can display in an image control which would also work.

The idea with this method is that you do this for setting up your authenticator from the QR code or setup code.

As part of the setup process you'll also need to verify that it's working before you enable two-factor authentication. So a typical Web Form will ask to scan the QR Code and then also provide an initial one time code to verify that it works. Only after that code has been verified should you actually enable two-Factor auth in your application.

Validating a Two-Factor One-Time Code

Once Two-Factor auth has been enabled, you can now log in with your username/password auth and then immediately also check the two factor auth.

loAuth = CREATEOBJECT("TwoFactorAuthentication")

*** Test with a 'known' Customer Secret Key (from my site's test account)
*** In a real app you'd retrieve this from a user/customer record
lcSecret = GETENV("TWOFACTOR_SECRETKEY")

*** Capture Pin (lookup in 1Password, Authy, Google or Microsoft Authenticator, Yubikey etc.
lcPin = InputForm("","Enter generated two-factor pin")
IF EMPTY(lcPin)
   RETURN
ENDIF

*** Check the One Time Code
If(loAuth.ValidatePin(lcSecret,lcPin))
   ? "Pin has been validated"
ELSE
   ? "Invalid Pin code"   
ENDIF

So then I can use my matching user account that matches the secret key, and now use the generated one-time code out of 1Password:

I can paste the value and the Authenticator checks for validity.

Two-Factoring: Logic is up to you

The code I've shown provides the logistics, but how you implement it is up to you. You can use Two-Factor auth in Web apps where it's quite common, but as you've seen here it's also possible to do this in Desktop applications as long as you can display a QR code - or you can optionally just use the Manual Setup code.

Add Spellchecking to your applications

Demonstrates:

Using a third party library
Dealing with Assembly Version Mismatches
Using a static Factory method
Using instance methods
Creating a wrapper class
Using a Generic List
Wrapping a .NET Collection with FoxPro Collection
Checking text spelling and generating spelling suggestsions
NuGet Library used: [WeCantSpell.HUnspell]https://github.com/aarondandy/WeCantSpell.Hunspell

Spellchecking is a useful feature if you're dealing with text applications and you can easily integrate a library that can check for misspelled words and suggests correctly spelled words on a misspelling.

Again, I'm not going to provide an integrated solution here, but just the tools to access this functionality. For a complete solution you likely need additional text parsing of larger blocks of text that looks at each word and then somehow highlights each misspelled word and displays a dropdown of suggestions.

Here's an implementation in Westwind Html Help Builder (a FoxPro application using an HTML based Markdown editor interface):

The editor parses each paragraph for individual words and then feeds each words into the spell checker in FoxPro. If a word is not spelled correctly the editor highlights the word, and on right click requests a list of suggestions that are then displayed in the drop down.

Spell Checking with WeCantSpell.Hunspell

The interface to this library is pretty straight forward:

A static factory method initializes a 'word list'
The word list is used to check spelling
The word list is used to provide a list of suggestions

A good way to start is to look at LinqPad to see what the .NET code looks like which is often cleaner and helps with figuring out what the exact types are:

One thing that jumps out here is that the list of suggestions is returned as a IList<string> result. This is a generic list result which is significant in that generic types are not directly supported in COM or FoxPro and can't be passed back into FoxPro. So we know that the call to the Suggest() method will have to be an indirect call via loBridge.InvokeMethod().

Let's look at the mapped FoxPro code:

loBridge = GetwwDotnetBridge()

loBridge.LoadAssembly("WeCantSpell.Hunspell.dll")

*** Location of Dictionary Files *.dic and *.aff
dictFolder = FULLPATH("bin\")

*** Creates a Spellchecker instance by loading dictionary and grammar files
loSpell = loBridge.InvokeStaticMethod("WeCantSpell.Hunspell.WordList",;
                                    "CreateFromFiles",;
                                    dictFolder +"en_US.dic",;
                                    dictFolder + "en_US.aff")

? "*** Check 'Colour' (en_US)"
? loSpell.Check("Colour")   && false
?
? "*** Check 'Color' (en_US)"
? loSpell.Check("Color")   && true
?

? "*** Suggestions for misspelled 'Colour'"
loSuggestions = loBridge.InvokeMethod(loSpell,"Suggest","Colour")

*** loSuggestions is a  `ComArray` Instance (IList<string>)
? loSuggestions.Count

*** Iterate over array items
FOR lnX = 0 TO loSuggestions.Count -1
   ? loSuggestions.Item(lnX)
ENDFOR

And that works just fine. We can call .Check() directly because it's a very simple method with simple parameters. The .Suggest() method returns a list and in order to access collection values and especially generic list values, we need to use InvokeMethod() to execute the code from within .NET. The result is returned as a ComArray instance, and we can use the .Count and .Item() method to retrieve the individual values.

Wrapper Class Makes it easier

Although the above code is easy enough to use, it's really a good idea to abstract this functionality into a class. You don't want to have to remember how to make the two InvokeMethod() calls and then deal with the ComArray instance. Instead we could create a class that automatically initializes the wordlist and then stores it internally. We can implement a .Spell() method that simply passes through, but for the .Suggest() method we can perhaps turn the ComArray into a native FoxPro Collection.

Here's what that looks like:

*************************************************************
DEFINE CLASS HunspellChecker AS Custom
*************************************************************

oBridge = null
oSpell = null
cLanguage = "en_US"
cDictionaryFolder = "" && root

************************************************************************
FUNCTION init(lcLang, lcDictFolder)
****************************************
IF EMPTY(lcLang)
   lcLang = this.cLanguage
ENDIF
IF EMPTY(lcDictFolder)
   lcDictFolder = this.cDictionaryFolder
ENDIF
   
this.oBridge = GetwwDotnetBridge()
IF ISNULL(this.oBridge)
      ERROR "Failed to load HUnspell: " + this.oBridge.cErrorMsg
ENDIF

LOCAL loBridge as wwDotNetBridge
loBridge = GetwwDotnetBridge()
if(!loBridge.LoadAssembly("WeCantSpell.Hunspell.dll"))
  ERROR "Failed to load WeCantSpell.Hunspell.dll: " + this.oBridge.cErrorMsg
ENDIF

IF !EMPTY(lcDictFolder)
	lcDictFolder = ADDBS(lcDictFolder)
ELSE
    lcDictFolder = ""
ENDIF

THIS.oSpell = loBridge.InvokeStaticMethod("WeCantSpell.Hunspell.WordList",;
                                    "CreateFromFiles",;
                                  lcDictFolder + lcLang + ".dic",;
                                  lcDictFolder + lcLang + ".aff")

IF ISNULL(this.oSpell)
  ERROR "Failed to load HUnspell: " + this.oBridge.cErrorMsg
ENDIF

ENDFUNC
*   init

************************************************************************
FUNCTION Spell(lcWord)
****************************************
LOCAL llResult

IF ISNULLOREMPTY(lcWord) OR LEN(lcWord) = 1
   RETURN .T.
ENDIF

llResult = this.oSpell.Check(lcWord)

RETURN llResult
ENDFUNC
*   Spell

************************************************************************
FUNCTION Suggest(lcWord)
****************************************
LOCAL loWords, lnX

loCol = CREATEOBJECT("collection")

*** Returns a Collection of values (not an array)
loWords = this.oBridge.InvokeMethod(this.oSpell,"Suggest",lcWord)

lnCount = loWords.Count

FOR lnX = 0 TO lnCount -1
    *** return indexed value (0 based) from the list collection
    lcWord = loWords.Item(lnX)
    loCol.Add( lcWord )
ENDFOR


RETURN loCol
ENDFUNC
*   Suggest

************************************************************************
FUNCTION Destroy()
****************************************

*** MUST dispose to release memory for spell checker
*this.oSpell.Dispose()
this.oSpell = null

ENDFUNC
*   Destroy

ENDDEFINE

This makes it much easier to create an instances of the class and keep it around for the duration of the application. You'll want to minimize loading this class as loading the dictionary from disk initially can be on the slow side (takes a second or two).

Beyond that the Suggest() method returns a cleaner FoxPro collection that you can FOR EACH over and use with more familiar 1 based array logic.

Using this class the previous code gets a little simpler yet:

*** Using the Wrapper Class
CLEAR

*** Loads library and dictionary - you can cache this for reuse
loSpell = CREATEOBJECT("HunspellChecker","en_US",".\bin")   


? "*** Check spelling for:"
? "Testing: " + TRANSFORM( loSpell.Spell("Testing")  )

? "Tesdting: " + TRANSFORM(loSpell.Spell("Tesdting")      )


lcWord = "aren'tt"
? "Suggestions for " + lcWord
loSug = loSpell.Suggest(lcWord)
? loSug.Count
FOR EACH lcWord in loSug
  ? lcWord
ENDFOR
loSpell = null

loSpell = CREATEOBJECT("HunspellChecker","de_DE",".\bin")

? "*** Using German Dictionary:"
? "Zahn: " + TRANSFORM(loSpell.Spell("Zahn"))
? "Zahnn: " + TRANSFORM(loSpell.Spell("Zahnn"))     
? "ZÃ¤hne: " + TRANSFORM(loSpell.Spell("ZÃ¤hne"))  
? "lÃ¤uft: " + TRANSFORM(loSpell.Spell("lÃ¤uft"))

? "***  Suggest for ZÃ¤hjne"
loSug = loSpell.Suggest("ZÃ¤hjne")
FOR EACH lcWord in loSug
  ? lcWord
ENDFOR
     
? loSug.Count
loSpell = null


? "*** Text to check:"
TEXT TO lcText
These ae somme of the worsd that are badly mispeled.

I cannot imaggine that somebody can spel so bad.

ENDTEXT

Note that you can spell check for different languages by applying the appropriate dictionary files. HUnspell uses standard dictionary files that are also used by OpenOffice and you can download other languages from there.

Finally, here's a rudimentary implementation that lets you get all misspelled words in a paragraph or other lengthy block of text and then also return the suggestions for the misspelled words:

loSpell = CREATEOBJECT("HunspellChecker","en_US",".\bin")   
loWords = GetWords(lcText)

LOCAL lnX
? "*** Mispelled words:"
FOR lnX = 1 TO loWords.Count   
   lcWord = loWords.Item(lnX)
   lcSuggest = ""

   IF (!loSpell.Spell(lcWord))
      loSug = loSpell.Suggest(lcWord)
      IF (loSug.Count > 0)
      	  
          FOR lnY = 1 TO loSug.Count
			lcSuggest = lcSuggest + loSug.Item(lnY) + " "
	   	  ENDFOR
	  ENDIF
	  
	  ? lcWord + " - " + lcSuggest   
	ENDIF
	
ENDFOR

From here you can build an interactive solution to integrate spellchecking into your own applications.

A Library with Dependency Issues

It turns out this library is distributes as a .NET Standard library which means that it's not specifically targeted at .NET Framework (ie. 4.72 or later) but rather uses a more generic target. It also takes advantage of some newer .NET features that are not part of the core framework and require additional dependencies.

As you can see there are several extra libraries that have to be distributed. That's easy enough, however it turns out that other applications also have dependencies on these same libraries and require slightly different versions.

When this happens it's necessary to set up the appropriate assembly redirects that roll up to the latest version of each library. To do this you have to edit the following files:

Yourapp.exe.config
vfp9.exe.config (in the VFP9 install folder)

<?xml version="1.0"?>
<configuration>
  <startup>   
	<supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.8" />	
  </startup>
  <runtime>
    <loadFromRemoteSources enabled="true"/>
      
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
            <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" culture="neutral" />
            <bindingRedirect oldVersion="0.0.0.0-13.0.0.0" newVersion="13.0.0.0" />
            </dependentAssembly>
            <dependentAssembly>
            <assemblyIdentity name="System.Runtime.CompilerServices.Unsafe" publicKeyToken="b03f5f7f11d50a3a" culture="neutral" />
            <bindingRedirect oldVersion="0.0.0.0-6.0.0.0" newVersion="6.0.0.0" />
            </dependentAssembly>
            <dependentAssembly>
            <assemblyIdentity name="System.Memory" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
            <bindingRedirect oldVersion="0.0.0.0-4.1.0.0" newVersion="4.0.1.2" />
            </dependentAssembly>
            <dependentAssembly>
            <assemblyIdentity name="System.Buffers" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
            <bindingRedirect oldVersion="0.0.0.0-4.1.0.0" newVersion="4.0.3.0" />
       </dependentAssembly>
     </assemblyBinding>     
     
  </runtime>
  
</configuration>

It's important to note that the versions in the assembly bindings are Assembly Versions not File Versions. You can find assembly versions in tools like ILSpy by looking at each assembly and looking at the metadata for the assembly.

Humanize numbers, dates, measurements

Demonstrates:

Using a third party library
Creating a Wrapper Class in .NET to avoid type complexity
Create a Wrapper class in FoxPro for ease of use
Work with Extensions Methods in .NET
Nuget Library: Humanizer

In this example, we'll see an example of creating a custom .NET DLL of our own and calling it from FoxPro. Humanizer is a cool library for text formatting that - as the name suggests - provides friendly naming for many common types. For example, things like using Today or 10 days ago for dates, turning numbers into strings, pluralizing text, camel or snake casing un-casing of text, turning bytes into friendly descriptions and so on.

Examples of Humanizing Number, Dates, Words, Sizes, and more

What's different with this example and why I prefer to delegate access of features to a .NET wrapper class is that Humanizer implements most of its functionality as extension methods and it uses a lot of nullable types. It's possible to access these features through wwDotnetBridge, but it's just significantly easier to do from within .NET and it's possible to create a very simple .NET class that exposes the features we want directly to FoxPro without the need of a FoxPro wrapper class.

To demonstrate some of the features of Humanizer and the functions I've exposed here's an example of the FoxPro code that uses the .NET wrapper component first:

loBridge = GetwwDotnetBridge()
loBridge.LoadAssembly("wwDotnetBridgeDemos.dll")

*!*	? "*** Raw Date to String"
*!*	*  public static string Humanize(this DateTime input, bool? utcDate = null, DateTime? dateToCompareAgainst = null, CultureInfo culture = null)      
*!*	ldDate = DATE() + 22
*!*	? loBridge.InvokeStaticMethod("Humanizer.DateHumanizeExtensions","Humanize",ldDate,null,null,null)  
?

*!*	? "*** Raw Number to String"
*!*	lnValue = 121233
*!*	* public static string ToWords(this int number, CultureInfo culture = null)       
*!*	? loBridge.InvokeStaticMethod("Humanizer.NumberToWordsExtension","ToWords",lnValue, null) + ;
*!*	"  (" + TRANSFORM(lnValue,"9,999,999") + ")"
*!*	?

*** Using a .NET Wrapper Class

LOCAL loHuman as wwDotnetBridge.FoxHumanizer
loHuman = loBridge.CreateInstance("wwDotnetBridgeDemos.FoxHumanizer")

? "*** Human Friendly Dates"
? loHuman.HumanizeDate(DATE()-1)            && yesterday
? loHuman.HumanizeDate(DATETime() + 86500)  && tomorrow
? loHuman.HumanizeDate(DATE() + 2)          && 2 days from now
? loHuman.HumanizeDate(DATETIME() - 55)     && 55 seconds ago
? loHuman.HumanizeDate(DATETIME() - 3800)   && an hour ago
?

? "*** Number to Words"
? loHuman.NumberToWords(10)        && ten 
? loHuman.NumberToWords(1394)      && one thousand three hundred ninety four
?
? "*** Pluralize"
? loHuman.Pluralize("Building")    && Buildings
? loHUman.Pluralize("Mouse")       && Mice
?

? "*** Numbers and Pluraize together"
? loHuman.ToQuantity("Car",3)       && three cars
? loHuman.ToQuantity("Mouse",3)     && three mice
?

? "*** Bytes, kb, megabytes etc. from bytes"
? loHuman.ToByteSize(13122)         && 12.81 KB
? loHuman.ToByteSize(1221221)       && 1.16 MB           
? loHuman.ToByteSize(1221221312)    && 1.14 GB

Humanizer has a ton of features and I've just exposed a few of them in the .NET class. Here's the C# class code:

/// <summary>
 /// Helper to create humanized words of numbers dates and other occasions
 /// 
 /// Wrapper around hte Humanizer library:
 /// https://github.com/Humanizr/Humanizer
 /// </summary>
 public class FoxHumanizer
 {

     /// <summary>
     /// Humanizes a date as yesterday, two days ago, a year ago, next month etc.
     /// </summary>
     public string HumanizeDate(DateTime date)
     {            
         return date.Humanize(utcDate: false);
     }

     /// <summary>
     /// Turns integer numbers to words
     /// </summary>
     public string NumberToWords(int number)
     {            
         return number.ToWords();
     }

     /// <summary>
     /// Returns a number like 1st, 2nd, 3rd
     /// </summary>
     public string NumberToOrdinal(int number)
     {
         return number.Ordinalize();
     }

     public string NumberToOrdinalWords(int number)
     {
         return number.ToOrdinalWords();
     }

     /// <summary>
     /// creates expression like one car or two bananas
     /// from a qty and a string that is pluralized as needed
     /// </summary>
     public string ToQuantity(string single, int qty)
     {
         return single.ToQuantity(qty, ShowQuantityAs.Words);
     }


     public string ToCamelCase(string input)
     {
         return input.Camelize();
     }

     /// <summary>
     /// Truncates a string and adds elipses after length is exceeded
     /// </summary>
     public string TruncateString(string input, int length)
     {
         return input.Truncate(length);
     }

     /// <summary>
     /// Takes a singular noun and pluralizes it
     /// </summary>
     public string Pluralize(string single)
     {
         return single.Pluralize(true);
     }

     /// <summary>
     /// Takes a pluralized noun and turns it to singular
     /// </summary>
     public string Singularize(string pluralized)
     {
         return pluralized.Singularize(true);
     }

     /// <summary>
     /// Returns a byte count as kilobytes, Mb or Gb
     /// </summary>
     public string ToByteSize(int byteSize)
     {
         return byteSize.Bytes().Humanize("#.##"); 
     }
     
 }

Humanizer has a ton of features, so I picked specific features that I am interested in to expose in the FoxPro class. If there are other use cases that I have not figured out here I can add them separately.

If I want to update the code I can simply update the code and rebuild the wwDotnetBridgeDemos.csproj project which lives in its own folder in .\Dotnet\wwDotnetBridgeDemos.

To update the code and assuming I have the .NET SDK installed on my machine I can simply run the following from a terminal in that folder:

dotnet build wwDotnetBridgedemos.csproj

The project is set up to automatically build into the .\bin folder but make sure you've shut down FoxPro if the library was previously loaded.

Why use a .NET Class?

So why did I use a .NET class if it's possible to call the code from FoxPro? In some cases it's simply easier to use .NET code to call functionality in .NET. Humanizer in particular uses a couple of features that are a little tricky to access from FoxPro.

Consider this LinqPad code:

Most of Humanizer's methods are heavily overloaded extension methods that use nullable types all of which are not super easy to call from FoxPro using wwDotnetBridge. It's possible, but it's super time consuming to find the right overload to call and then set up the ComValue structure correctly to support the nullable values.

It's simply easier and also considerably more efficient to use a .NET wrapper directly for these calls especially since our own classes can be designed to be explicitly FoxPro friendly so they can be directly invoked without any of the wwDotnetBridge proxy helper methods.

A File System Watcher and Live Reload (Event Handling)

Demonstrates:

Using built-in .NET functionality
Handling events via a Callback class
Useful for document change notifications
Useful for a Live Reload Manager
Uses System.Net.FileSystemWatcher

The .NET FileSystemWatcher is a very useful built-in class that can be used to monitor changes in the file system. You can enable the file watcher to notify you when files change, are added, deleted or renamed. There are many uses for this functionality especially in document centric applications.

Real World Examples of Monitoring Files

For example, I use this functionality in Markdown Monster for example to detect when a document I'm editing has changed. If my document has no changes I can automatically update the document with the new changes from disk, or if there are changes I can pop up a notice when saving that the file has been changed since opening. At that point I can pop up a dialog letting me choose between my copy, the changed copy, or do text merge in a Comparison Tool (BeyondCompare for me). Here's what this looks like:

The way this works is that the File Watcher is created when the document is opened and I check for any changes for that specific file only. Then based on current document state the code executes an update or sets a flag that triggers the dialog on save.

Another use case for this is in Web Connection for the Live Reloading the server if FoxPro code has changed. I can basically monitor for any code changes to PRG files, and if one has been change I can automatically restart the Web server application and run with the new change and at the same time trigger a page refresh in the browser to reload the page. Meanwhile the Web Connection Web connector which also uses a FileSystemWatcher monitors for changes to Web files and automatically triggers a browser refresh when HTML, CSS or JS files change.

It's a powerful feature and there are lots of use cases for it.

Using Async Callbacks to get File System Notifications in FoxPro

The FileSystemWatcher is a tricky component to work with, as it doesn't allow for filtering, so you basically monitor changes to all files and then handle filtering as part of your event handling code. The component uses events which is something new to discuss in regards of FoxPro and wwDotnetBridge access to this component.

Let's start with the setup code that starts the file monitoring:

loBridge = GetwwDotnetBridge()

IF EMPTY(lcFileList)
   lcFileList = "*.prg,*.ini,*.fpw,*.bak,"
ENDIF
IF EMPTY(lcFolder)
   lcFolder = SYS(5) + CurDir()
ENDIF

*** Create an instance of the file watcher: MUST PERSIST!!!
PUBLIC __WWC_FILEWATCHER
__WWC_FILEWATCHER = loBridge.CreateInstance("System.IO.FileSystemWatcher",lcFolder)
__WWC_FILEWATCHER.EnableRaisingEvents = .T.
__WWC_FILEWATCHER.IncludeSubDirectories = .T.

*** Create the Handler Object that responds to events
loEventHandler = CREATEOBJECT("FileWatcherEventHandler")
loEventHandler.cFileList = lcFileList

*** Create a subscription to the events
loSubscription = loBridge.SubscribeToEvents(__WWC_FILEWATCHER, loEventHandler)
loEventHandler.oSubscription = loSubscription  && so we can unsubscribe

? "Watching for file changes in: " + lcFolder + " for  " + lcFileList

The code creates a new FileSystemWatcher instance and enables listening to events. We specify a folder to monitor recursively and allow raising of events. The watcher exposes a number of events and we need to implement all events of the interface even if we are only interested in a few or even one event. This is similar to the way COM events are handled via FoxPro INTERFACE.

Next we create an Event Subscriptiong by calling SubscribeToEvents() to which we pass the object that we want to handle events on and an event handler object - that's the object that implements the methods matching the event signatures in .NET.

The events are fired asynchronously, meaning the event handler methods are fired out of band and the code immediately following the SubscribeToEvents() immediately returns and keeps on running. The events fire in the background, out of band.

The event handler class is then called when something interesting happens - in this case when files are changed in some way. For this example, I'm simply writing the operation and filename to the desktop, but you can do anything you want from within the event code.

You do however, want to minimize the code you run in the event handler and have it touch as little shared data as possible. It's best to consider event handlers as data drops where you dump some data that can be picked up by the main application at a later time. This can be as simple as setting one or more variables that are later read, or writing a record to a database table that is later read.

Here's the EventHandler class:

*************************************************************
DEFINE CLASS FileWatcherEventHandler AS Custom
*************************************************************

*** File extensions to monitor
cFileList = "*.prg,*.vcx,*.exe,*.app,*.ini"

*** Optional comma list of folders to exclude (ie: \temp\,\web\)
cFolderExclusions = ""

*** File watcher subscription
oSubscription = null

nLastAccess = 0

************************************************************************
FUNCTION HasFileChanged(lcFilename as String)
****************************************
LOCAL lcFileList, lnX, lnFiles, lcExtension, lnExclusions
LOCAL ARRAY laExtensions[1]
LOCAL ARRAY laExclusions[1]

IF EMPTY(lcFileName)
   RETURN .F.
ENDIf


IF ATC("\temp\",lcFileName) > 0
   RETURN .F.
ENDIF

lnExclusions = 0
IF !EMPTY(THIS.cFolderExclusions)
	lnExclusions = ALINES(laExclusions,this.cFolderExclusions,1 + 4, ",")
	FOR lnX = 1 TO lnExclusions
	    IF ATC(LOWER(laExclusions[lnX]),lcFileName) > 0
	       RETURN .F.
	    ENDIF
	ENDFOR
ENDIF

lcFileList = STRTRAN(THIS.cFileList,"*.","")
lnFiles =  ALINES(laExtensions,lcFileList,1 + 4,",")
        
FOR lnX = 1 TO lnFiles
    lcExtension = LOWER(JUSTEXT(lcFileName))
    IF lcExtension == LOWER(laExtensions[lnX])
       this.nLastAccess = SECONDS()
       RETURN .T.
    ENDIF
ENDFOR

RETURN .F.
ENDFUNC
*   HasFileChanged


************************************************************************
FUNCTION OnCreated(sender,ev)
****************************************
LOCAL lcFile 

lcFile = THIS.GetFilename(ev)
IF THIS.HasFileChanged(lcFile)
   ? "File has been created: " +lcFile
ENDIF
	
ENDFUNC

FUNCTION OnChanged(sender,ev)
LOCAL lcFile 

lcFile = THIS.GetFilename(ev)

IF THIS.HasFileChanged(lcFile)
	? "File has been changed: " + lcFile
ENDIF

ENDFUNC

************************************************************************
FUNCTION OnDeleted(sender, ev)
******************************
LOCAL lcFile 

lcFile = THIS.GetFilename(ev)
IF THIS.HasFileChanged(lcFile)
	? "File has been deleted: " + lcFile
ENDIF

ENDFUNC

************************************************************************
FUNCTION OnRenamed(sender, ev)
******************************
LOCAL lcFile 

IF VARTYPE(ev) # "O"
   RETURN
ENDIF

*** RenamedEventArgs apparently doesn't allow direct access
loBridge = GetwwDotnetBridge()
lcOldFile = loBridge.GetProperty(ev,"OldFullPath")
IF EMPTY(lcOldFile)
   RETURN
ENDIF
lcNewFile = loBridge.GetProperty(ev,"FullPath")
IF EMPTY(lcNewFile)
   RETURN
ENDIF

? "File has been renamed: " + lcOldFile + " to " + lcNewFile

ENDFUNC

************************************************************************
FUNCTION Destroy()
******************

IF THIS.oSubscription != null
	THIS.oSubscription.UnSubscribe()
	THIS.oSubscription = null
ENDIF
   
IF VARTYPE(__WWC_FILEWATCHER) = "O"
   __WWC_FILEWATCHER.Dispose()
   __WWC_FILEWATCHER = .F.
ENDIF

ENDFUNC

ENDDEFINE

The file watcher has no file matching filters that can be applied to the events which means that you have to filter for files that you want to watch as part of the event handlers you implement. If you're only interested in PRG files you need to check what files are incoming and immediately exit if it's not what you want.

Another tricky part about the file watcher is knowing exactly what the event interface looks like which in this case can be found here.

As mentioned all events on the event interface have to be implemented, but you can certainly provide do nothing event handling the simple exit immediately. If you don't care about renaming, just immediately return in the OnRenamed event.

When you run this demo you might also notice that some events like the change events fire multiple times. That's because there are filters that you can set on what can be monitored and many file operation might trigger for multiple matches to these triggers. It might be file data change and data change. Making the file watcher behave often involves ignoring repeated events and playing around with the event filters.

Regardless of the minor issues, a Filewatcher is a powerful tool that's useful for a ton of features.

Async: Print Html to Pdf

Demonstrates:

Calling async Task methods
Using Callback handlers to handle async completions
Find out how to turn HTML to PDF
NuGet Library: Westwind.WebView.HtmlToPdf

This is a small example that demonstrates how to print HTML documents to PDF files. This is useful for Web and desktop applications that can output reports and documents to HTML and turn that HTML into PDF files that can be emailed or published.

This and the following example require the use of async Task code in .NET as the task of printing to PDF can take a bit of time. So rather than waiting for completion the operation is async and calls you back when the task is complete.

Introducing InvokeTaskMethodAsync()

wwDotnetBridge includes a InvokeTaskMethodAsync() which calls an async method and responds back via a Callback object that you pass in. This is similar to the way the FoxPro EVENTHANDLER() function works except that we're passing the callback and event method through to .NET rather than to a COM object.

The AsyncCallbackEvents handler object that is passed to the method is notified when the async operation completes either via a OnComplete() or OnError() handler. Unlike the event interface we discussed in the last example, here we only have to implement two methods and they always have the same signature, although OnComplete() will receive a different result each time, depending on a successful return value from the async operation.

Printing PDF Output from HTML Input

Let's take a look by way of an example that uses a third party (mine) .NET component that converts PDF documents to HTML using the Edge WebView runtime in Windows using the Westwind.WebView.HtmlToPdf component.

Let's start with the mainline setup code that starts the Html to Pdf operation.

LPARAMETER lcUrl, lcOutputFile

*** Has to be persist after program ends 
PUBLIC loCallbacks

IF EMPTY(lcUrl)
   lcUrl = "Assets/HtmlSampleFile-SelfContained.html"
ENDIF
IF EMPTY(lcOutputFile)
   lcOutputFile = "c:\temp\htmltopdf.pdf"
ENDIF   
IF !StartsWith(lcUrl, "http")  
   *** Assume it's a path - fix it up
   lcUrl = GetFullPath(lcUrl)
ENDIF

CLEAR 
? "*** Generating PDF from " + lcUrl
? "*** To " + lcOutputFile

LOCAL loBridge as wwDotNetBridge
loBridge = GetwwDotnetBridge()
loBridge.LoadAssembly("Westwind.WebView.HtmlToPdf.dll")

*** Create the .NET class
loPdf = loBridge.CreateInstance("Westwind.WebView.HtmlToPdf.HtmlToPdfHost")

*** Create the Callback Handler Object
loCallbacks = CREATEOBJECT("PdfCallbacks")
loCallbacks.cOutputFile = lcOutputFile
ERASE (lcOutputFile)

loSettings = null
loSettings = loBridge.CreateInstance("Westwind.WebView.HtmlToPdf.WebViewPrintSettings")

*** Async PDF Generation Method: Exits immediately
loBridge.InvokeTaskmethodAsync(loCallbacks, loPdf,
                               "PrintToPdfAsync", lcUrl, 
                               lcOutputFile, loSettings)

? "*** Converting to PDF - this may take a few seconds..."
GoUrl(lcUrl)   && Display PDF

The base behavior for this class is very simple - you call a single method to perform the Html to PDF conversion. You basically provide a Url or Filename to an HTML document, and an optional output filename. The engine then renders the HTML in the WebView instance and uses the WebView's built-in PDF engine - the same engine that's used for printing and PDF printing - and renders the active HTML document as best as it can to PDF.

PDF Output Generation isn't an exact Science

PDF output is basically Print output, so the PDF output generated will be the same as what you see in Print Preview window of any Chromium browser. So if you want to get an idea how well PDF printing works for a specific document/url you can test the output before you ever try to print it.

Print output of HTML can be effected by HTML styling - not everything that renders well as HTML prints well. Additionally it's very useful to add print specific CSS styling that simplifies HTML rendering, uses specific built-in fonts etc. to optimize printing. When it comes to print output simpler is better - and plain semantic HTML (ie. document centric output) works best.

The call PrintToPdfAsync() is async so it returns immediately. You pass in a Callback handler object that is called back when the print operation completes - or fails. You also pass the Url, output file and a settings object which allows customizing a few things about the PDF output generation.

Here's what the Callback object looks like:

DEFINE CLASS PdfCallbacks as AsyncCallbackEvents

*** Capture output file 
cOutputFile = ""

FUNCTION OnCompleted(lvResult,lcMethod)

IF !lvResult.IsSuccess
   ? "ERROR: " + lvResult.Message
   RETURN
ENDIF

GoUrl(THIS.cOutputFile)
? "*** PDF Output Generated!"

ENDFUNC

FUNCTION OnError(lcMessage, loException, lcMethod)

? "Error: " + lcMethod,lcMessage

ENDFUNC

ENDDEFINE

You inherit from AsyncCallbackEvents and implement two methods:

OnCompleted(lvResult, lcMethod)
OnError(lcMessage, loException, lcMethod)

The reason for inheriting is that in some cases you may not need to handle either of these methods - in fire and forget scenarios for examples. In other cases you don't care about errors and you can omit the OnError handler - the base class can capture and ignore the events. One of these two events will always be called though - and hence the base class to ensure that the methods exist.

In this example, on success we simply go and display the PDF file in the browser via GoUrl(this.cOutputFile). Note that the class adds a custom cOutputFile property that is set when the class is instantiated. Use the property interface to pass values that you need from the mainline into the callback class.

As with the Event code in the previous example, keep event handler methods very short running and have minimal impact on the application state. Ideally capture what you need store it somewhere and then process it from the mainline code.

Here's what the output from the parameterless sample looks like from a local self-contained long HTML document printed to PDF:

The demo displays both the original HTML and converted PDF document. Here's another example by running to a specific Url:

DO PrintToPdf with "https://microsoft.com"

Here's what the Microsoft Site output looks like (they do a pretty good job with their Print stylesheet):

Note that the print results may very in quality, depending how well the URL/HTML support print output via a print specific stylesheet. The library adds some basic print styling but PDF rendering may not do a great job on really complex, and non-semantic HTML documents. It does however very well with very document centric output like documentation or output from - Markdown documents.

Async: OpenAI Calls

Demonstrates:

Calling async Task methods
Using Callback handlers to handle async completions
Use an OpenAI API library to access various OpenAI services online and locally
Some useful scenarios for AI
NuGet Library: Westwind.Ai

For this example I'll create several different types of AI interfaces that perform specific tasks:

Text Summarization
Translations
Generic Chat Completions
Image Generation

OpenAI is a company, but the company was one of the first to expose AI as a service, using the OpenAI HTTP API. This API has become an unofficial open standard and so you find OpenAI style APIs that work with multiple AI engines. In this example, we'll use the HTTP service via front end library that abstracts and wraps the API communications and handles the async calls to the server.

Westwind.AI Library

To do this I'll use one of my own .NET Libraries called Westwind.AI that can interface via HTTP with any OpenAI style API. Using this library you can easily connect to:

OpenAI
Azure OpenAI
Local Ollama Models
Any generic OpenAI server

The library is set up in a way that you can easily switch between service providers so you can quickly switch between online models and local models.

The library supports both Chat Completion interfaces as well as image generation via the OpenAI Dall-E 3 model.

Online or Local AIs? LLMs and SLMs - Oh my!

AI comes in all sorts of sizes, but most of you are probably familiar with the large public models or LLMs (Large Language Models) like ChatGPT or CoPilot (Microsoft), Gemini (Google), Llama (Meta) and Grok (X). These are commercial Chat bots that typically run in the browser and communicate with online APIs to provide AI results.

ChatGPT and CoPilot both use OpenAI's models, and they are at the moment typically using GTP-4 or GPT-4o-mini to serve chat requests.

Web based chat bots are cool to play with and useful for assistance tasks, but you can also access these very same models directly from your applications, by using the OpenAI API that is exposed by OpenAI, and Microsoft's Azure services online, or for local machines and many supported local models using Ollama (there are others that also use OpenAI APIs but I haven't tried them since Ollama works well). In other words you can use the APIs to access the power of both online LLMs and offline SLMs (Small Language Models) that can run offline on your own machine.

At the moment online models tend to be much better at providing results, and also much faster than local models. Running local models on non-AI optimized hardware is pretty slow even when running on a reasonably poweful GPU. While many results for say summarizing a 5000 word document via an LLM takes maybe 5 seconds, it can take 30 seconds with a local SLM. The results also tend to be much more... variable with local SLMs. Most of the SLMs I've used for the examples I show here, produce very inconsistent results while the online LLM provide pretty solid results. I suspect this will improve in the future as LLMs are quickly becoming unsustainable for energy and resource usage, and more AI processing eventually will have to local machines. But we're not there yet...

So for best results you'll likely want to use one of the major online LLMs and this library specifically supports OpenAI and Azure OpenAI. Both of these run OpenAI models and if you're using one of these you'll likely use either gpt-4o-mini or gpt-4o. The mini model is smaller, faster and much cheaper version of the full blown gpt-4 models.

Both of these online models are paid services and you pay for API access. OpenAI has a pretty simple credit card signup process and you are charged in relatively small increments. Pricing is quite reasonable even though I use the Image Generation and AI features in Markdown Monster extensively I only replenish my account's $20 balance limit once every two months. Azure Open AI has more complex billing tied to Azure and it uses the same models that OpenAI publishes (with some delay in latest model availability). But it's much more complex to host models as you in effect host your own model service that is tied to a specific model type. Using Azure only makes sense if you have free credits because of a subscription or benefit of some kind, or if you are already heavily using Azure.

Running Local AI Models

Although I mentioned that local models tend to be slower and generally less accurate, it's still very cool that you can run models locally. One huge benefit of running local models in a tool like Ollama is that you are not sending your inputs to an online provider so you have privacy. Also the offline models tend to have much more lax rules of what is allowed in AI output generation. With online models it's very easy to run into safety restrictions when running chat or image queries while local models tend to have restrictions dialed down by default. There are definite free speech restrictions that come into play often in unexpected ways especially as chat and image queries are fixed up by the AI engines. It's much more pronounced with the online services, less so with local AIs although it all depends on how the AI model was tuned.

IAC, for local models I recommend using Ollama which is a locally installable AI Host server. You can download and install it on Windows, and then use command line commands to pull down and run models locally. By default there's a command line interface that you can use, but a better way is to install Open WebUI which lets you run a local browser Chat interface to Ollama. This is similar to ChatGPT or CoPilot, but using local models. Open WebUI also lets you find and download models, and easily switch between multiple installed local models.

Generic Chat Completions from FoxPro

Ok, let's take a look at a few practical examples using Chat Completions. Chat completions is basically the same interface that you use with ChatGPT or CoPilot where you specify a prompt and the AI provides a response. You can provide an Input Prompt which is your request, and also a System Prompt which assigns the AI a Role. The default role of most general purpose AIs is You are a helpful assistant., but you can modify that.

So I start with two practical examples that provide Text Summaries and Language Translation.

Text Summary

So the first example is using chat completions to do text summaries of a block of text. This is a quite useful feature and using the library I use here, relatively easy to do.

Let's start with LinqPad to see what the .NET code looks like:

As you can see the key bit of code is the async call:

string result = await chat.Complete(prompt, systemPrompt, false);

Like in the Html to Pdf example we'll need to using InvokeTaskMethodAsync() with a Callback object in FoxPro in order to get asynchronously called back when the relatively slow chat completion returns:

LPARAMETERS lcTextToSummarize
LCOAL loBridge as wwDotNetBridge, loCompletions

loBridge = GetwwDotnetBridge()

*** Using OpenAI API
loConnection = loBridge.CreateInstance("Westwind.AI.Configuration.OpenAiConnection")
loConnection.ApiKey = GETENV("OPENAI_KEY")
loConnection.ModelId = "gpt-4o-mini"  && "gpt-3-turbo" (default so not really neccessary)

IF EMPTY(lcTextToSummarize)
    ? "Please provide some text to summarize."
	RETURN
ENDIF

*** Create Chat client and pass configuration
loCompletions = loBridge.CreateInstance("Westwind.AI.Chat.GenericAiChatClient", loConnection)

*** Our prompt text/question
lcPrompt = lcTextToSummarize

*** Specify a role for the AI
lcSystem = "You are a technical writer and are tasked to summarize input text succinctly " +;
           "in no more than 4 sentences. Return only the result summary text."

*** Callback object that fires OnComplete/OnError events translation is done
loCallback = CREATEOBJECT("OpenAiCallback")
loCallback.oCompletions = loCompletions  

*** Async call starts here - returns immediately
loBridge.InvokeTaskMethodAsync(loCallback, loCompletions,"Complete",lcPrompt, lcSystem, .F.)

? "*** Program completes. Async call continues in background."
? "Summarizing..."

This code is made up of three steps:

Setting up the OpenAI Connection
Setting up the prompt
Calling the OpenAI API

The code's comments describe each operation, as it occurs. The async call returns immediately and there's no success or failure information. Instead the result is handled in the OpenAiCallback class which implements the OnCompleted() and OnError() methods:

DEFINE CLASS OpenAICallback as AsyncCallbackEvents

oCompletions = null

*** Returns the result of the method and the name of the method name
FUNCTION OnCompleted(lcResult,lcMethod)

IF (this.oCompletions.HasError)
    ? "Error: " + THIS.oCompletions.ErrorMessage
    RETURN
ENDIF

? "Summary:"
? "----------"
? lcResult

ENDFUNC

* Returns an error message, a .NET Exception and the method name
FUNCTION OnError(lcMessage,loException,lcMethod)
? "Error: " + lcMethod,lcMessage
ENDFUNC

ENDDEFINE

To test this out you can copy some text to the clipboard and let it summarize. Just for kicks I took the massive Markdown content of this very white paper and put it in my clipboard. On my machine the result comes back in about 3-4 seconds with a very capable response.

The OnCompleted() method receives the result value from the async call, along with the name of the method that was called. The latter can be useful if you use the same Callback handler for multiple methods or calls simultaneously and these results might come back at different times.

The value in this case is a text completion, so it's plain text.

OpenAI responses can be returned as text, which in many cases can be markdown. For direct scenarios like the above of text summarization the text is usually returned as plain text as there's nothing to really format. However, for more complex results you will often see Markdown. We'll look at some examples later that demonstrate how to deal with that.

Translations

For the next example lets do essentially the same thing, except this time we'll run translations from one language to another. Essentially the code here is nearly identical to the last example, except that the prompt and system prompt are different along with some of the messages:

LPARAMETERS lcTranslateText, lcLanguage

*** We have to keep the completions alive
loBridge = GetwwDotnetBridge()
loBridge.LoadAssembly("Westwind.Ai.dll")

lcOpenAiKey = GETENV("OPENAI_KEY")

loConnection = loBridge.CreateInstance("Westwind.AI.Configuration.OpenAiConnection")

loConnection.ApiKey = lcOpenAiKey
loConnection.ModelId = "gpt-4o-mini"

IF EMPTY(lcTranslateText)
   lcTranslateText = "Genius is one percent inspiration, ninety-nine percent perspiration."
ENDIF
IF EMPTY(lcLanguage)
  lcLanguage = "German"
ENDIF  

loCompletions = loBridge.CreateInstance("Westwind.AI.Chat.GenericAiChatClient", loConnection)
lcSystem = "You are a translator and you translate text from one language to another. " +;
           "Return only the translated text."
lcPrompt = "Translate from English to " + lcLanguage + CHR(13) + CHR(13) + lcTranslateText

*** Set up the callback event handler - OnCompleted/OnError
loCallback = CREATEOBJECT("OpenAiCallback")
loCallback.oCompletions = loCompletions && pass so we can access in callback

*** Make the API call asynchronously - returns immediately
loBridge.InvokeTaskMethodAsync(loCallback, loCompletions,"Complete",lcPrompt, lcSystem, .F.)

? "Translating from English..."
? "--------------"
? lcTranslateText

****************************************************************
DEFINE CLASS OpenAICallback as AsyncCallbackEvents
**************************************************
oCompletions = null

*** Returns the result of the method and the name of the method name
FUNCTION OnCompleted(lcResult,lcMethod)

IF (this.oCompletions.HasError)
    ? "Error: " + this.oCompletions.ErrorMessage
    RETURN
ENDIF

? "To German:"
? "----------"
? lcResult
ENDFUNC

FUNCTION OnError(lcMessage,loException,lcMethod)
? "Error: " + lcMethod,lcMessage
ENDFUNC

ENDDEFINE

Again this sample works best with text from the clipboard. Select and copy some text, then translate by doing:

DO openAITranslation with _Cliptext, "German"


DO openAITranslation with _Cliptext, "French"

Cool, right?

Again, if you run these operations multiple times, you'll find that each time it'll translate slightly differently using different words or phrasings. OpenAI does a pretty good job however - I speak fluent German and it usually returns even colloquial German text, even though there's variance.

Using Local LLMs with Ollama

Using the OpenAI online model uses the OpenAIConnection like this:

*** Using OpenAI API
loConnection = loBridge.CreateInstance("Westwind.AI.Configuration.OpenAiConnection")
loConnection.ApiKey = GETENV("OPENAI_KEY")
loConnection.ModelId = "gpt-4o-mini"  && "gpt-3-turbo"

For OpenAI you specify your API key and optionally a model id. In this case the model ID isn't really necessary because currently gpt-4o-mini is the default model.

If I want to run this same example with a local SLM model via Ollama I can do that as well - all I have to do is change the connection. Assuming Ollama is running on my machine, I can change the Connection configuration to:

*** Using Ollama SMLs Locally
loConnection = loBridge.CreateInstance("Westwind.AI.Configuration.OllamaOpenAiConnection")
loConnection.ModelId = "llama3"    && specify a local model (llama3, phi3.5, mistral etc.)

Local Ollama doesn't require an API key so the only thing you have to provide is the local model you want to run. Even that is optional as the default active model is used.

Running against a local model you'll quickly find out that requests are significantly slower and that results are much more variable.

For example, llama3 (Meta's model that has an SLM version) often ignores my request to only return the actual results. For summaries it often refuses to stick to the 4 paragraph limit and gives me a freaking novel instead. phi3.5 (Microsoft's SLM model) often produces bad translations that miss words.

The OpenAI LLMs do a much better job at returning results quickly, and producing more consistently accurate results.

Generic Chat Completions

The last two examples showed how to create specific implementation of chat completions with pre-defined prompts and tasks: Text summarization and translation specifically.

But sometimes it's also useful to just have a generic AI that can provide completely random information. And that's easy to do by simply changing around the way the prompt and system prompt are handled.

Same idea as the last examples, except in this version we can pass in the prompt directly along with an optional system prompt.

LPARAMETERS lcPrompt, lcSystemPrompt

do wwDotNetBridge
DO markdownParser

LOCAL loBridge as wwDotNetBridge, loCompletions
loBridge = GetwwDotnetBridge()
loBridge.LoadAssembly("Westwind.Ai.dll")

lcOpenAiKey = GETENV("OPENAI_KEY")

*** Open AI Connection with gpt-4o-mini
loConnection = loBridge.CreateInstance("Westwind.AI.Configuration.OpenAiConnection")
loConnection.ApiKey = lcOpenAiKey

IF EMPTY(lcPrompt)
   lcPrompt = "How do I make an Http call in FoxPro with wwHttp?"
ENDIF
IF EMPTY(lcSystemPrompt)
  lcSystemPrompt = "You are a general purpose, helpful assistant"
ENDIF  

poCompletions = loBridge.CreateInstance("Westwind.AI.Chat.GenericAiChatClient", loConnection)

loCallback = CREATEOBJECT("OpenAiCallback")
loCollback.oCompletions = loCompletions
loBridge.InvokeTaskMethodAsync(loCallback, loCompletions,"Complete",lcPrompt, lcSystemPrompt, .F.)

? "Thinking..."
? "--------------"
? lcPrompt

Nothing new here, except I'm passing in the lcPrompt and optional lcSystemPrompt so we can do:

DO openAICompletions with "Tell me about the history of Southwest Fox"

This time the result will likely be a little different with more information and the interfaces tend to return text as Markdown. Notice at the top I DO MarkdownParser which was covered in one of the earlier samples. We'll use the Markdown parser to parse the result to HTML and then display the result in a templated HTML template so it looks nice.

As before the results are handled in the Async Callback via the OpenAiCallback class:

DEFINE CLASS OpenAICallback as AsyncCallbackEvents

oCompletions = null

*** Returns the result of the method and the name of the method name
FUNCTION OnCompleted(lcResult,lcMethod)

IF (This.oCompletions.HasError)
    ? "Error: " + THIS.oCompletions.ErrorMessage
    RETURN
ENDIF

*** Convert to Markdown (MarkdownParser.prg)
lcHtml = Markdown(lcResult)

? "Done!"

*** Show Web Page with Formatting
ShowWebPage(lcHtml)

ENDFUNC

* Returns an error message, a .NET Exception and the method name
FUNCTION OnError(lcMessage,loException,lcMethod)
? "Error: " + lcMethod,lcMessage
ENDFUNC

ENDDEFINE

Here's what the result looks like with the result returned in a couple of seconds:

While it's cool to see this work and come back with a useful result, think hard about whether you need this functionality built into your app. Essentially this is similar to the type of output you get from ChatGPT or CoPilot which frankly might be better options for users for these types of generic queries. Unless you have very specific use cases like the Translation or Summarizing example I showed it's probably best to avoid having generic AI content embedded in your own apps.

Image Generation

Ok the last AI example is a little different in that it creates image output from an input prompt. OpenAI's Dall-E model allows turning text into images.

Here's an example:

The results can be pretty cool like the one above, but it might take more than a few tries to arrive at good useful examples. It's also extremely important that you describe your image in great detail, including some directions on what style and coloring the image should use for example.

Without more fanfare here's the code to generate an image:

LPARAMETERS lcPrompt, lcImageFile

do wwDotNetBridge
DO markdownParser

LOCAL loBridge as wwDotNetBridge
loBridge = GetwwDotnetBridge()
loBridge.LoadAssembly("Westwind.Ai.dll")

lcOpenAiKey = GETENV("OPENAI_KEY")

loConnection = loBridge.CreateInstance("Westwind.AI.Configuration.OpenAiConnection")
loConnection.ApiKey = lcOpenAiKey
loConnection.ModelId = "dall-e-3"
loConnection.OperationMode = 1  && AiOperationModes.ImageGeneration=1

IF EMPTY(lcPrompt)
   lcPrompt = "A Fox that is dressed as a grungy punk rocker, " +;
              "rocking out agressively on an electric guitar. " + ;
              "Use goldenrod colors on a black background in classic poster style format."	 
ENDIF

loPrompt = loBridge.CreateInstance("Westwind.AI.Images.ImagePrompt")
loPrompt.Prompt = lcPrompt

loImageGen = loBridge.CreateInstance("Westwind.AI.Images.OpenAiImageGeneration", loConnection)

loEventHandler = CREATEOBJECT("OpenAICallback")

*** Pass these so they stay alive and can be accessed in the event handler
loEventHandler.oPrompt = loPrompt
loEventHandler.oImageGen = loImageGen

*** Here we need to match the signature EXACTLY which means ACTUAL enum object
enumOutputFormat = loBridge.GetEnumValue("Westind.AI.Images.ImageGenerationOutputFormats","Url")
* enumOutputFormat = loBridge.GetEnumValue("Westind.AI.Images.ImageGenerationOutputFormats","Base64")
loBridge.InvokeTaskMethodAsync(loEventHandler, loImageGen, "Generate", loPrompt, .F., enumOutputFormat) 

? "Generating Image..."
? "--------------"
? lcPrompt

DEFINE CLASS OpenAICallback as AsyncCallbackEvents

oPrompt = null
oImageGen = null

*** Returns the result of the method and the name of the method name
FUNCTION OnCompleted(llResult,lcMethod)

IF (!llResult)
    ? "Error: " + this.oImageGen.cErrorMsg
    RETURN
ENDIF

lcUrl = this.oPrompt.FirstImageUrl

? "*** Image URL returned by API:"
? lcUrl
?
? "*** Revised Prompt (AI fix-up)"
? this.oPrompt.RevisedPrompt
?

GoUrl(lcUrl)  && Show the Url

*** Download the image
lcImageFile = "d:\temp\imagegen.png"

*** Download the file using .NET
LOCAL loBridge 
loBridge = GetwwDotnetBridge()
loWebClient = loBridge.CreateInstance("System.Net.WebClient")
loWebClient.DownloadFile(lcUrl, lcImageFile)

*** Download file with wwHttp
*!*	DO wwhttp
*!*	loHttp = CREATEOBJECT("wwHttp")
*!*	loHttp.Get(lcUrl,  lcImageFile)

GoUrl(lcImageFile)  && Show the local file

? "*** Done!"
ENDFUNC

* Returns an error message, a .NET Exception and the method name
FUNCTION OnError(lcMessage,loException,lcMethod)
? "Error: " + lcMethod,lcMessage
ENDFUNC

ENDDEFINE

ImageGeneration uses an ImagePrompt class that is used to pass in parameters and also retrieve results. You pass in the Prompt object instance, which is initially populated with the prompt. Upon processing, the Prompt instance is filled with additional data that includes the FirstImageUrl when generating an image URL, or Base64Data when generating the raw data. Image generation returns an array of images but the API only ever returns a single image which is returned with FirstImageUrl or the Base64Data. You specify which mode - Url or Base64 - is used via the ImageGenerationsOutputFormats enum which is passed as the last parameter into the Generate() async method:

*** Here we need to match the signature EXACTLY which means ACTUAL enum object
enumOutputFormat = loBridge.GetEnumValue("Westind.AI.Images.ImageGenerationOutputFormats","Url")
* enumOutputFormat = loBridge.GetEnumValue("Westind.AI.Images.ImageGenerationOutputFormats","Base64")
loBridge.InvokeTaskMethodAsync(loEventHandler, loImageGen, "Generate", loPrompt, .F.,enumOutputFormat)

After generation ImageGeneration() also sets a RevisedPrompt which is an modified prompt that AI engine fixes up before rendering the image. The prompt tends to be embellished with additional information and styling which is sometime pretty hilarious - and at other times can trigger the safety triggers of the AI engine, which is not so funny.

To get an idea of the Prompt and its many properties, look at ILSpy:

In the code example above I returned the URL so the code displays the URL using GoUrl() (from wwUtils.prg) to display the image in the browser. For bonus points the result handler also downloads the image using .NET's System.Net.WebClient and storing it in a file. Alternately you can also use wwHttp if you have it using FoxPro only code.

For returning base64, we can ask for the image to be returned as base64, which is an HTML style image embedding url (data:image/png;base64,<largeBase64Text>) , which can be parsed to binary or by using the convenient loPrompt.SaveImageFromBase64(lcFileToSaveTo) provided by the .NET library. Both Url and base64 work, but base64 is slower as it has to immediately download the image, while URL can just display the URL. URLs are stored only for a limited time on OpenAI, so you'll want to download the URLs if you want to keep any images as soon as you know you want to hang on to them.

There are two programs that demonstrate both URL and base64 downloads:

OpenAiImage.prg (Url)
OpenAiImageBase64.prg

How do I use this?

The features I've described here I've actually integrated in one of my tools Markdown Monster. Markdown Monster has support for Text Summaries, Translation, Grammar Checking and Image AI generation.

Here's an example of the AI based Grammar check of a text selection:

Similar specialized dialogs exist for translations, and text summaries that can be embedded or replace existing text.

Image generation is integrated with an interactive editor and image manager that can be used to capture and embed images:

All of these features are implemented using the same library I've shown in the samples above, so these examples are real world integrations that are in production in a commercial application.

AI Summary

Using this AI library makes short work of integrating AI functionality into applications. What I've shown are kind of boring, but practical applications of AI functionality that I've actually used and which is probably a good use of this technology.

Keep in mind that in the current state, AI serves best as an assistant that helps with existing tasks and operations, rather than as a reliable automation tool.

Although there's tons of talk how AI will eat the world, finding more innovative usage for this tech is not easy, because it's really hard to predict exactly what the result from an AI queries look like. As you've seen even with these simple examples, results can vary wildly between runs, even with the same exact data and even with very simple deterministic requests.

So, play around with AI features, but be mindful of how reliable the tools are for the job that you need it to actually perform, before jumping in over your head.

Create a .NET Component and call it from FoxPro

In the course of the examples I've shown there were a couple (wwDotnetBridge 101 and Humanizer) where I demonstrated using a .NET class of our own to create logic. Let's take a look and see how we can actually do that, using the new and much lighter weight .NET SDK tools, that require no specific tools.

The good news is that there's now a .NET SDK that you can download that includes everything you need to compile, build and run .NET applications. It's a single, couple of minutes install and you're ready to start creating .NET code. All you really need is:

.NET SDK (download)
A text editor
A Powershell or Command Terminal Window

You don't need Visual Studio any longer, although if you plan on doing serious .NET development and you want to effectively debug components you build you may still want to use it. Regardless though you can use the SDK and Visual Studio - or any other .NET tools side by side interchangeably.

It's not your Windows .NET anymore

Part of the reason for this shift to more generic tooling is that .NET is no longer a Windows only platform - you can build .NET applications for Mac and Linux. In fact any non-UI and Web applications you build tend to be completely cross-platform out of the box unless you explicitly add platform specific features (ie. Windows API calls, or UI features).

For purposes of this discussion, the goal is to create a .NET Class library that we can call from FoxPro, which means we want to create a new Class Library project.

Creating new Projects

.NET now lets you create new projects from the command line via the dotnet new command.

For FoxPro usage we preferably create projects for .NET Framework - which targets net472 or net481 (4.7.2 recommended since it covers a wider ranger of stock installations).

Unfortunately the SDK does not allow creating .NET Framework projects directly, even though the SDK certainly supports building NET Framework projects. The problem is that newer project types use features that aren't supported for .NET framework, so while you can easily create .NET Core projects and make a few changes, it's a bit of a pain.

The closest you'll get is by targeting netstandard2.0. .NET Standard works with .NET Framework, but ideally you want to target net472 so we'll end up using netstandard2.0 and changing the target.

Let's start by going to a parent folder into which we want to create a new project (for samples, into the dotnet folder to create dotnet\FoxInterop)

Make sure you explicitly specify the target framework and use -f netstandard2.0 as it's the only bare bones project type that's close to what you want for .NET framework.

# go to a parent folder - project is created below
dotnet new classlib -n FoxInterop -f netstandard2.0
cd FoxInterop

# Open an editor in the folder - VS Code here
code .

Here's what you'll see:

So you'll want to change the target from netstandard2.0 to net472:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net472</TargetFramework>
  </PropertyGroup>

</Project>

The class generated is empty.

using System;

namespace FoxInterop
{
    public class Class1
    {

    }
}

And now you're off to the races.

Output to a specific Folder

If you're building for FoxPro you'll likely want your .NET output to go to a specific. It turns out that by default output is created in a complex folder structure below the project.

If you'd rather put the output in your application's output folder (or a bin folder as I like to do for me dependencies) you can change the project file to the following:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>    
    <TargetFramework>net472</TargetFramework>    

    <!-- Optional: Output to a specific folder -->    
    <OutputPath>..\..\bin</OutputPath>
    <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>    

  </PropertyGroup>
</Project>

In this case I dump the output directly into my bin folder where the samples can find it.

Creating a Sample Class

To create something semi-useful lets create a .NET class and see if we can compile it and access it from FoxPro:

namespace FoxInterop
{
    public class Person
    {
        public string Name { get; set; } =  "Jane Doe";
        public string Company { get; set; } = "Acme Inc.";
        public DateTime Entered { get; set; } = DateTime.UtcNow;
        public Address Address { get; set; } = new Address();

        public override string ToString() 
        {
            return $"{Name} ({Company})\n${Address}";
        }
    }

    public class Address
    {
        public string Street { get; set; }  =  "123 Main St.";
        public string City { get; set; }    =  "Anytown";
        public string State { get; set; }   =  "CA";
        public string PostalCode { get; set; }  =  "12345";

        public override string ToString() 
        {
            return $"{Street}, {City}, {State} {PostalCode}";
        }
    }

}

The Person class has a few simple properties as well as a nested Address object that is automatically initialized. This is good practice to ensure that the Address is never null even if it can be 'empty'.

Build the Project

Next you'll need to actually build the project and you can do this from the Terminal via dotnet build from the project's folder.

Here's what a sucessful build looks like using the built-in terminal in VsCode:

If the compilation works you'll see a success message, otherwise you'll get an error in the command window along with a line number reference that you can click on:

Use it in FoxPro

Assuming you get a successful build, the project has built a .NET Assembly (a DLL) into the .\bin folder where it's accessible to our FoxPro code.

Note that there's _startup.prg that adds the .\Bin folder to FoxPro's path and allows .NET assemblies to be loaded out of that folder. All samples call the _startup.prg just in case it's not explicitly set.

So now we can create an instance of our .NET class quite simply. You can type the following into the FoxPro command window, or - better - create a small PRG file to run the code.

CLEAR
DO _startup.prg

DO wwDotnetBRidge
loBridge = GetwwDotnetBridge()
? loBridge.LoadAssembly("foxInterop.dll")
loPerson = loBridge.CreateInstance("FoxInterop.Person")

*** Access the default property values
? loPerson.Name
? loPerson.Entered

*** Call a method
? loPerson.ToString()

You can also access the nested Address object individually:

? loPerson.Address.Street
? loPerson.Address.City
? loPerson.Address.ToString()

Next, in the C# code, let's add a collection of addresses and update the ToString() code to display those addresses if they are present:

public List<Address> AlternateAddresses { get; set; } = new List<Address>();

public override string ToString() 
{
    var output =  $"{Name} ({Company})\n${Address}";

    if (this.AlternateAddresses.Count > 0)
    {
        foreach (var addr in AlternateAddresses)
        {
            output += $"\n${addr}";
        }
    }
    return output;
}

Now rebuild the project from the Terminal:

dotnet build

But - you likely are running into a problem now, namely that the output assembly is locked, because the FoxPro application has it loaded. So you first have to unload FoxPro (or any running application using the assembly).

Then do the build again. Now it works!

Launch FoxPro again and let's add some more code to our test program to add a couple of new alternate addresses.

Let's start by accessing the AlternateAddresses. Notice that the type is List<Address> which is a Generic List object. If you recall, Generics cannot be accessed by FoxPro directly, so we have to indirectly access using GetProperty():

*** Get ComArray of Address
loAddresses = loBridge.GetProperty(loPerson,"AlternateAddresses")

? loAddresses.Count && 0

GetProperty() in this case returns a ComArray object which is an object wrapper around .NET collections. The wrapper allows you to read, add, update and delete items in many different array, list, collection and dictionary types.

In this case we want to add a new item which we can do by using CreateItem() to create a new object of the list's item type, and Add() it to the address collection:

*** Create a new detail items
loAddress = loAddresses.CreateItem()
loAddress.Street = "3123 Nowhere Lane"
loAddress.City = "Nowhere"

*** Add to the list of addresses
loAddresses.Add(loAddress)

loAddress = loAddresses.CreateItem()
loAddress.Street = "43 Somewhere Lane"
loAddress.City = "Somewhere"

*** Add to the list of addresses
loAddresses.Add(loAddress)

*** Print - should include the new address
? loPerson.ToString()

Using .NET from FoxPro is a good Choice for many Scenarios

And there you have it - it's pretty simple to create a .NET component and call it from FoxPro.

This is quite useful if you need to interact with .NET components that:

Require lots of code to interact with
Require complex types that are hard to access from FoxPro

As a general rule these days for almost every FoxPro application I create one matching .NET assembly into which I can then easily stuff many small .NET components that can all be called from FoxPro rather than having to figure out how to call various components from FoxPro using wwDotnetBridge indirect access methods. Unless code is super simple, I almost always rather opt for writing in .NET code vs. writing verbose code in FoxPro.

As a bonus this allows you to get your feet wet with .NET code. Using class library extensions like this is a great way to create small bits of .NET code without having to go full bore of a full conversion. You can gain external functionality that otherwise wouldn't be there while still maintaining the ability to easily edit and recompile the code for changes.

##AD##

Configuration and Application Management

.NET Configuration: .config Files

The full framework .NET Framework is configured via .config files that are bound to the executable that launches the application process. This can be confusing for FoxPro applications, because in FoxPro we tend to have two types of launching applications and therefore two different kinds of config files:

YourApp.exe.config
Vfp9.exe.config

.NET Configuration files are XML based and they look something like this:

<?xml version="1.0"?>
<configuration>
  <startup>   
	<supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" />	
  </startup>
  <runtime>
    <loadFromRemoteSources enabled="true"/>
      
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
            <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" culture="neutral" />
            <bindingRedirect oldVersion="0.0.0.0-13.0.0.0" newVersion="13.0.0.0" />
            </dependentAssembly>
       </dependentAssembly>
     </assemblyBinding>     
  </runtime>
  
</configuration>

supportedRuntimeVersion

The supportedRuntime key is not really required any longer as .NET has become very stable. If the supportRuntime is not specified the current installed version is used - typically .NET 4.8.1 these days. This key is used to specify a minimum supported runtime in order for the application to start. If for some reason some ancient version of .NET is installed prior to 4.7.2 - the app will show a message on startup and not run. These days, any machine that's reasonably current will have the latest .NET version installed and there haven't been any major changes since 4.7.2 that break functionality.

loadFromRemoteResources

loadFromRemoteSources is an important setting - it ensures that the host process can load .NET assemblies from network locations without using an explicit .NET security policy. Native .NET executables don't have to do this, but Visual FoxPro applications require this setting due to the way the runtime is hosted.

assemblyBinding

Finally the assemblyBinding section can be used to resolve assembly dependency version mismatches by specifying a specific version of an assembly that should be used regardless of the version that is requested by a dependency. More on that in the next section.

There are many more configuration settings that are supported in the .config file. Any .NET settings that are supported via app.config configuration can also be used in your FoxPro applications. For example, you can use appSettings for configuration settings, set trace settings, output tracelogs to disk and much more. Possible but probably not something that you need to do for FoxPro integrations - but it's available if you need it.

.NET Dependency Version Management

One issue that you can run into and that's somewhat important is one of versioning of depdencies. When you use .NET components you may end up using dependencies that are used by multiple components with each version depending on a different version.

.NET - and especially .NET framework - is determinisitic about versions it expects so when a component is bind to a component of a certain type by default it expects that specific version to be present. If it's not you may end up getting assembly load errors, that complain that one or another assembly could not resolve its dependencies.

This situation is better in .NET Core which automatically rolls up dependencies to the highest version, but in .NET Framework you have to do this manually via configuration called Assembly Redirects.

Assembly redirects let you specify a minimum version and desired higher version. By having a redirect all components requesting a specific versions are then 'redirected' to the higher version and so all can share the same version safely.

Assembly redirects are set in .config files. For FoxPro that means:

YourApp.exe.config
VFP9.exe.config

and here is what Assembly Redirects look like if they are needed:

<?xml version="1.0"?>
<configuration>
  <startup>   
	<supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.8" />	
  </startup>
  <runtime>
    <loadFromRemoteSources enabled="true"/>
      
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
            <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" culture="neutral" />
            <bindingRedirect oldVersion="0.0.0.0-13.0.0.0" newVersion="13.0.0.0" />
            </dependentAssembly>
            
            <dependentAssembly>
            <assemblyIdentity name="System.Runtime.CompilerServices.Unsafe" publicKeyToken="b03f5f7f11d50a3a" culture="neutral" />
            <bindingRedirect oldVersion="0.0.0.0-6.0.0.0" newVersion="6.0.0.0" />
            </dependentAssembly>
            <dependentAssembly>
            <assemblyIdentity name="System.Memory" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
            <bindingRedirect oldVersion="0.0.0.0-4.1.0.0" newVersion="4.0.1.2" />
            </dependentAssembly>
            <dependentAssembly>
            <assemblyIdentity name="System.Buffers" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
            <bindingRedirect oldVersion="0.0.0.0-4.1.0.0" newVersion="4.0.3.0" />
       </dependentAssembly>
     </assemblyBinding>     
  </runtime>
  
</configuration>

If you're using a single component you're unlikely to run into issues, but for all these demos I'm doing here, there are many different versions of components used and so a conflict is more likely and we're seeing it here.

NewtonSoft.Json is a very widely used JSON parser in .NET so it's often involved in dependency management fix ups.

The various System assemblies are typically caused by components that are using netstandard2.0 instead of explicitly targeting .NET Framework (net472 etc.). If there are multiple components that are using netstandard2.0 it's very likely there will be a version conflict.

So how do you find these problems? When you get an error with a specific assembly you are loading it will typically tell you which dependency is a problem. You can then use a disassembly like ILSpy to check what version is expected and fix the version.

Assembly Versions is what matters for Assembly Redirects

It's important to note that the versions in the assembly bindings are Assembly Versions not File Versions. You can find assembly versions in tools like ILSpy by looking at each assembly and looking at the metadata for the assembly. Don't rely on the File Properties window in Explorer which shows the File version.

Assembly redirects can be a pain to track down, but thankfully they are relatively rare.

Keep it simple: Use .NET When wwDotnetBridge is a lot of Effort

I want to stress once again, to make sure you don't make things too complicated with trying at all costs to keep code purely in FoxPro. Yes, wwDotnetBridge makes it possible to access most .NET code directly, but trust me when I say that it's much easier to create code with proper Intellisense and the ability to directly access the entire language feature set directly rather than having to make indirect calls from FoxPro.

As a bonus by doing this you can isolate the .NET Wrappers in a way so that they are FoxPro friendly so that you can directly access and use the .NET component from FoxPro without a wrapper.

You can create many components in a single .NET project, and .NET assemblies tend to be tiny and very efficient to load. Since you're already going to call into .NET code creating a small wrapper that's FoxPro accessible is going to have virtually no overhead - in fact it'll likely be much more efficient than making indirect calls using wwDotnetBridge.

Take advantage of .NET.

Get your Feet Wet with .NET

Using components is one of the easiest ways to get your feet wet with some .NET code without having to jump into building an entire application. You can slice off some business functionality into .NET or even just those pieces that you can't directly call from FoxPro otherwise.

Many of the success stories of people that have migrated have come from starting very small and getting a feel for it with a few small features and then expanding outwards from there. wwDotnetBridge makes it entirely feasible to build a hybrid application that works both with FoxPro and .NET.

As an example, West Wind Html Help Builder which is a very old FoxPro application integrates heavily with .NET. There are entire sub-components that are written in .NET including the Class and Database Importer, the CHM output generation engine, and large parts of the editor interface. There are even a number of UI Dialogs that are .NET based due to odd behaviors of FoxPro dialogs.

If this sounds like I'm shilling for .NET - in a way I am, but I do so because it has worked extremely well for me. .NET is the easiest platform that you can directly interface with from FoxPro including for desktop applications. There are many other toolsets like NodeJs, Phython, Java etc. that are popular and while I think they are equally as viable as standalone platforms, they don't have anything like .NET in terms of ease of integration with FoxPro or the vast array of Windows system integration. .NET is really the only high level tooling platform that can easily integrate with FoxPro via easy to use COM Interop.

So, take advantage of this easy integration, while gaining an enormous window of functionality that lets you continue to use FoxPro...

##AD##

Summary

Alright that oughta do it! ??

Let's do a high level sum-up:

Lots of cool .NET features available to integrate into FoxPro
- Many Windows System features are exposed through .NET
- Thousands of open source and 3rd parties are available
- With wwDotnetBridge you can access most of it!
wwDotnetBridge makes it EASY!
- Call any .NET components without registration
- Opens up most of .NET to FoxPro
- Access most .NET features including
  Generics, Value Types, Collections, Enums, Static members etc.
- Helpers for types that suck in FoxPro
  ComArray, ComValue
Create Wrappers for Complex Code
- Easier to create .NET code to interface with complex APIs
- Make the wrapper FoxPro friendly
- Call the Wrapper from FoxPro
- Create FoxPro Wrappers for .NET Code

Resources

wwDotnetBridge Documentation
GitHub Repository
- Code Samples
- White Paper
- Slides
Get wwDotnetBridge from GitHub
Slides for SWFox 2024 Session

this white paper was created and published with the Markdown Monster Editor

West Wind Web Connection 8.0 Release Notes

Rick Strahl — Wed, 26 Jun 2024 00:05:49 GMT

It's been a bit and Web Connection is turning 8.0! After six years of incremental improvements it's time to rev Web Connection to its next major version.

Although this is a major version release that has a number of significant updates, there is only one specialized feature (FTP) affected with breaking changes, so if you're upgrading from a v7 version, upgrades should be quick and easy like most other minor version updates.

For the last few years, the focus of Web Connection has been on continuous, small incremental feature enhancements and improvements around the development and administration process. So rather than huge, disruptive major releases updates, there have been gradual updates that come integrated one small piece at a time to avoid the big version shocks. This version rollover release has a bit more in the update department, but still follows the incremental improvement model and other than a single breaking change with the new FtpClient classes, this release has no breaking changes from recent v7 releases.

Links and Upgrades

Before we get into what's new, here are the links for the latest release, purchase and upgrade:

Web Connection Home
You can find the download for the Shareware version here.
Buy a Web Connection License
Purchase a full developer and 1 server license for Web Connection.
Buy a Web Connection Upgrade (from any version)
Purchase an upgrade for any version of Web Connection. All versions back to 1.x are allowed.

Existing Runtime License Upgrades

Runtime licenses don't have specific upgrade SKUs, but can still be upgraded at 50% of the full price. For upgrade runtime license purchases, pick a full runtime license and then apply the Promo Code: RUNTIME_UPGRADE if you qualify. This only applies only to Runtime Updates not to version updates or new purchases. Use this code with a single item of the Runtime you wish to upgrade only.

Free Upgrade if purchased after July 1st, 2023

If you purchased Web Connection 7.x on or after July 1st, 2023 you can upgrade for free until the end of 2024. Use promo code: FREE_UPGRADE. Use this code on an order with a single item of the Web Connection Upgrade only.

Note: Upgrades are always verified and these promo codes apply only to the specific upgradable item. Please use these specialized Promo Codes only on orders that qualify based on the two descriptions above. If you use these codes with other types of upgrades or orders your order will be rejected. We reserve the right to refuse upgrades based on non-conforming orders.

What's new

Let's take a look what's new in this release:

COM Server Management Improvements
Improved Web Connection Server Error Logging
New FTPClient Classes
New wwZipArchive Class
REST Service Token Authentication Support
wwRestProcess.lRawResponse Helper Property
wwDotnetBridge Improvements
JSON and REST Client Improvements
wwCache Improvements

More info on what's new in recent releases check out the What's New Page in the documentation.

COM Server Management Improvements

For deployed applications Web Connection should be run in COM mode, and COM mode includes an internal instance pool manager that makes it possible to effectively run FoxPro single threaded servers in a multi-threaded environment with simultaneous request handling. Getting the single threaded (or STA threaded really) FoxPro to behave in pure multi-threaded environment of .NET is a complex matter and involves a lot of trickery to make it work consistently and reliably.

In this release the COM Pool manager has seen a major refactoring:

Faster, parallelized Server Loading and Unloading
Servers are available as soon as they load
Reliable loading and unloading
No more double loading or unloading
All instance exes are released on unload (no more orphaned servers)
Improved error logging especially in detail mode

Web Connection has a long history of using COM Servers for production environments and while the technology and the implementation worked really well over the years all the way back to ISAPI, .NET, and now .NET Core, there have always been a few rough edges when it comes to server loading and unloading especially in very busy and high instance environments.

This release addresses these issue with a completely new pipeline for COM server loading and unloading that is reliable and - as a bonus - much quicker through parallelization of the load and unload processes.

You can get an idea of load/unload performance in this screen capture which demonstrates 5 server instances under heavy load from a West Wind WebSurge load test run, with the server pool constantly being loaded, unloaded, run as a single instance and the Application Pool being restarted:

Figure 1 - Web Connection COM Server Loading and Unloading Improvements

You can see that server loading is very fast, and if you look closely you can see instances immediately processing requests as the servers load, while the rest of the pool is still loading.

Servers are now loaded in parallel rather than sequentially which results in servers loading much quicker than previously. Additionally, servers are available immediately as soon as they enter the pool, while others are still loading. Previously the load process was blocked and sequential loading caused a potentially significant delay before processing could start. This doesn't matter much if you're running a few instances, but if you're running 10 or as many as 40 instances as one of our customers does, startup time can be a significant issue.

Additionally we fixed some related issues that in some cases caused double loading of server instances. Because the COM server load process first unloads before loading new instances, it was possible previously to end up in a scenario where instances were asking to unload while new instances where already loading. All of these issues have been addressed in the latest release with some creative thread management - ah, the joys of multi-threaded development ??

The changes have been made both the Web Connection .NET Module and the Web Connection .NET Core Web Server.

The Web Connection .NET Core Web Server

The Web Connection .NET Core Web Server was introduced with Web Connection 7.0 primarily as a tool to allow you develop locally without IIS. But it also to allows you distribute a local Web server with your own applications that let you effectively build and distribute local Web Applications that can run on a desktop machine. The .NET Core server middleware also supports running inside of IIS (if you want consistency between dev and production) and can even be used on non-Windows platforms like Linux either as a standalone Web server or a behind a reverse proxy server like NginX (but the FoxPro code still has to run on Windows).

Improved Web Connection Server Error Logging

In the process of updating the Web Connection server connectors we've also reviewed and updated the server logging that goes into the wcerrors.txt logs. We've cleaned up the error logging so that non-detail mode doesn't log anything but critical messages and errors - previously there were some ambiguous trace messages that often came up in discussion on the forums, but weren't actual errors. These have been removed, and you should now see a mostly blank wcerrors.txt file in normal operation, except if you start having problems with your servers.

Detail logging (LogDetail true in the configuration) logs a lot of error and non-error information into the log including request start and stop operations, request timings, application start and much more detailed error information on errors.

Detail mode now always shows the request id and thread information (if available) to more easily correlate requests in a busy error log.

Figure 2 - Web Connection Detail Error Logging

You'll also notice that the actual request completion or call error is marked with a *** prefix so it's more easily visible in the noise. The *** entries are either a completed request or the actual request processing error message that occurred during the COM call.

New FTPClient Classes

This release has a completely new set of FTPClient classes that replace the old wwFtp and wwSFTP classes. The new version uses a .NET based interface instead of the legacy WinInet features that are somewhat limited in that they didn't support the FTPS (FTP over TLS) protocol which to be frank makes them useless in today's environment where secure connections are a requirement.

The new version relies on two .NET libraries:

FluentFtp (for FTP and FTPS)
SSH.NET (for SFTP)

We've been using SSH.NET previously for SFTP support, but FluentFtp integration is new, and it provides for the new FTPS support in Web Connection (and the West Wind Client Tools).

The new classes are:

wwFtpClient (FTP and FTPS)
wwSFtpClient (SFTP)

The two classes have the exact same API surface except for connection information which is slightly different for SFTP which requires SSH keys or configuration files instead of username and password for standard FTP.

The new classes follow a similar interface to the old connection based wwFTP/wwFTPS classes, so if you used them with Connect()... FTP Operation... Close() operations the syntax will be identical and easy to upgrade. In most cases you should be able to simply change the class name - ie. change CREATEOBJECT("wwFtp") to CREATEOBJECT("wwFtpClient").

What's missing from the old wwFtp and wwsftp classes are the single method FTP operations for uploading and downloading. These were awkward to use with their long parameter lists anyway and the class based interface is cleaner to use anyway. The old wwFtp and wwSftp classes are still shipped in the \classes\OldFiles folder and can still be used - just copy them into your path and they'll work like before.

To demonstrate the new FtpClient functionality, here's an example that runs through most operations supported:

CLEAR
DO wwFtpClient
DO wwUtils   && for display purposes only

loFtp  = CREATEOBJECT("wwFtpClient")
loFtp.lUseTls = .T.
loFtp.cLogFile = "c:\temp\ftp.log" && verbose log - leave empty
loFtp.lIgnoreCertificateErrors = .F.   && self-signed cert not installed


*** cServer can be "someserver.com", "someserver.com:22", "123.213.222.111"
lcServer =  INPUTBOX("Server Domain/IP")
IF EMPTY(lcServer)
   RETURN
ENDIF

lcUsername = InputBox("User name")
IF EMPTY(lcUsername)
   RETURN
ENDIF

lcPassword = GetPassword("Password")
IF EMPTY(lcPassword)
	RETURN
ENDIF

*** Progress Events - class below
loFtp.oProgressEventObject = CREATEOBJECT("FtpClientProgressEvents")

loFtp.cServer = lcServer
loFtp.cUsername = lcUsername
loFtp.cPassword = lcPassword
*loFtp.nPort = 21 && only needed if custom port is required

IF !loFtp.Connect()
	? loFtp.cErrorMsg
	RETURN
ENDIF
? "Connected to " + lcServer	

loFtp.Exists("Tools/jsMinifier1.zip")


IF !loFtp.DownloadFile("Tools/jsMinifier.zip", "c:\temp\jsMinifier.zip")
	? loFtp.cErrorMsg
	RETURN
ENDIF	
? "Downloaded " + "Tools/jsMinifier.zip"

lcUploadFile = "Tools/jsMinifier" + SYS(2015) + ".zip"
IF !loFtp.UploadFile("c:\temp\jsMinifier.zip", lcUploadFile)
	? loFtp.cErrorMsg
	RETURN
ENDIF
? "Uploaded " + lcuploadFile

*** provide a folder name (no wildcards)
loCol = loFtp.ListFiles("/Tools")
IF ISNULL(locol)
   ? "Error: " + loFtp.cErrorMsg
   RETURN
ENDIF   
? TRANSFORM(loCol.Count ) + " matching file(s)"
? loFtp.cErrorMsg
FOR EACH loFile IN loCol FOXOBJECT
   IF ( AT("jsMinifier_",loFile.Name) = 1)
	   ? loFtp.oBridge.ToJson(loFile)  && for kicks print out as json
	   IF loFtp.DeleteFile(loFile.FullName)
	      ? "Deleted " + loFile.FullName
	   ENDIF
	   
   ENDIF
ENDFOR

loFiles = loFtp.ListFiles("/Tools")
FOR EACH loFile in loFiles
   ? loFile.Name + " " + TRANSFORM(loFile.LastWriteTime)
ENDFOR

* loFtp.Close()  && automatic when released

RETURN


DEFINE class FtpClientProgressEvents as Custom

FUNCTION OnFtpBufferUpdate(lnPercent, lnDownloadedBytes, lcRemotePath, lcMode)
  lcMsg = lcMode + ": " + TRANSFORM(lnPercent) + "% complete. " + lcRemotePath + " - " + TRANSFORM(lnDownloadedBytes) + " bytes"
  ? "*** " + lcMsg
ENDFUNC

ENDDEFINE

New wwZipArchive Class

This release also has a new ZipArchive class that provides more control over zip functionality using modern, native .NET and built-in functionality that removes the old dependency on Dynazip libraries.

The new class provides the ability to add files to existing zip files and iterate and retrieve files individually.

CLEAR
DO wwZipArchive

loZip = CREATEOBJECT("wwZipArchive")
lcZipFile = "d:\temp\zipFiles.zip"

*** Zip up a folder with multiple wildcards
*** 
IF !loZip.ZipFiles(;
   lcZipFile,;
   "*.fpw,*.vc?,*.dll,*.h",;  
   CURDIR(),;
   .T., .T.)
   ? "Zipping Error: " + loZip.cErrorMsg
   RETURN
ENDIF   
? loZip.cErrorMsg
   
*** add a single file   
IF !loZip.AppendFiles(lcZipFile, "wwZipArchive.prg")
   ? "Error: " + loZip.cErrorMsg
   RETURN
ENDIF
   
*** Unzip into a folder   
IF !loZip.UnzipFolder(lcZipFile, "d:\temp\Unzipped1")
   ? "Unzip Error: " + loZip.cErrorMsg
   RETURN
ENDIF

*** Look at all files in the zip   
loEntries = loZip.GetZipEntries(lcZipFile)
IF ISNULL(loEntries)
   ? "No entries:  " + loZip.cErrorMsg
   RETURN 
ENDIF
? loEntries.Count

*** Iterate through the collection
FOR EACH loEntry IN loEntries FoxObject     
	? loEntry.Name + "  " + ;
	  loEntry.Fullname + " " + ;
	  TRANSFORM(loEntry.Length) + " - " + ;
	  TRANSFORM(loEntry.CompressedLength)
ENDFOR   

*** Unzip an individual entry and unzip it - first in this case
loZip.UnzipFile(lcZipFile, loEntries[1].FullName, "d:\temp\" + loEntries[1].Name)

These functions use wwDotnetBridge and built-in .NET framework features for zipping files. Note that one thing missing here is support for encrypted Zip files which is not supported by the .NET APIs.

The old ZipFiles() and UnzipFiles() in wwAPI.prg are still available as well, but you need to make sure you have the dzip.dll and dunzip.dll files available in your distribution.

REST Service Token Authentication Support

Unlike standard wwProcess classes, wwRestProcess does not work with standard session cookies and by default all session support is turned off. However, you can enable session support via Bearer Token authentication which reads a user supplied identity token from the Authorization HTTP header.

There are two mechanisms available:

InitTokenSession
This method is the core feature that ties a generated token to a Web Connection wwSession object via its cSessionId parameter. InitTokenSession() either retrieves an existing session from a provided Bearer token, or if one isn't provided or matched provides an empty session. To create a new Token you can have a custom sign in method and call NewSession() to map your custom user/customer/etc. to a session with a session holding any additional data.
Authenticate()
If you want basic mapping of the session to a user in a similar way to the way HTML authentication works with cookies you can use the Authenticate() method which serves a dual purpose for:
- Validating a wwSession Token and Loading a User
- Authenticating user credentials

InitTokenSession() is the low level function that checks for bearer tokens and maps them onto a wwSession object. It generates new tokens on every request but only stores them if you explicitly save them in a sign in request. To see if a user has a previous approved token you can check !Session.lIsNewSession. This is pretty low level but provides to core feature of token management and whether a user has a token that matches an existing token.

FUNCTION OnProcessInit
...

*** Pick up existing token or create a new token
*** and set on the oSession object
THIS.InitTokenSession()

*** Define anonymous requests that don't need validation
lcScriptName = LOWER(JUSTFNAME(Request.GetPhysicalPath()))
llIgnoreLoginRequest = INLIST(lcScriptName,"testpage","signin")

*** Fail if no token and not a passthrough request
IF !llIgnoreLoginRequest AND this.oSession.lIsNewSession
   THIS.ErrorResponse("Access Denied. Please sign in first.","401 Unauthorized")
   RETURN .F.
ENDIF

RETURN .T.

Authenticate() maps on top of that functionality by taking a mapped token and mapping it to an UserSecurity object, providing all the familiar User Security features like the .oUser, lIsAuthenticated, cAuthenticatedUser etc. properties on the wwProcess class.

FUNCTION OnProcessInit
...

*** IMPORTANT: InitTokenSession is required to pick up the Bearer token
***            and load or create a new session
THIS.InitTokenSession()

*** Check for pages that should bypass auth - signin always (not signout though!)
lcScriptName = LOWER(JUSTFNAME(Request.GetPhysicalPath()))
llIgnoreLoginRequest = INLIST(lcScriptName,"testage","signin")

IF !llIgnoreLoginRequest
   *** Check for Authentication here based on the token (note no parameters)
   IF !this.Authenticate()   
	   THIS.ErrorResponse("Access Denied. Please sign in first.","401 Unauthorized")
	   RETURN .F. && Response is handled
   ENDIF
ENDIF

*** One you're here you can now acccess these anywhere in your process code:
llIsLoggedin = this.lIsAuthenticated
lcUsername = this.cAuthenticatedUser
loUser = this.oUser

RETURN .T.

Choose the Authenticate() approach if you need to know who your users are explicitly. Use the InitTokenSession() if you only need to know that they are have signed in and are validated. Authenticate() tries to map the token to a user and there are several overloads of this method with various parameter signatures. You can also override these methods with custom behavior for mapping users to tokens.

Beyond those two approaches you still need to actually validate a user via some sort of sign in operation that authenticates a user and then creates the actual token. This can be another endpoint or it could be an oAuth operation or even a standard Web page.

The following uses a REST endpoint in an existing API (ie. part of the REST service):

FUNCTION Signin
LPARAMETER loCredentials

*** Load some business object (or plain DAL code) that can authorize a user
loBus = CREATEOBJECT("cUser")

*** Use whatever custom Authorization you need to assign a token
IF !loBus.AuthorizeUser(loCredentials.UserName, loCredentials.Password)
   RETURN THIS.ErrorResponse(loBus.cErrorMsg,"401 Unauthorized")
ENDIF

*** Create a new Session and optionally assign a mapping user id
*** that links back to a user/customer record in the Application
lcToken = THIS.oSession.NewSession(loBus.oData.UserId)
THIS.oSession.SetSessionVar("tenant",loBus.oData.TenantId)
THIS.oSession.SetSessionVar("displayname",loBus.oData.dispName)
THIS.oSession.Save()  && Must explicitly save to Db


*** Return the token and expiration (or whatever you choose)
loToken = CREATEOBJECT("EMPTY")
ADDPROPERTY(loToken,"token", lcToken)
ADDPROPERTY(loToken,"expires", DATETIME() + 3600 * 24)

RETURN loToken  
* Returns JSON: { token: "<token>", expires: "2023-10-23T07:00:00Z" }
ENDFUNC

The focus behind this code is to create a new token with Session.NewSession() and then saving it into the session table.

The token is then returned to the client, who will then use it to pass in the Bearer token Authorization headers with their REST client requests. Something akin to this in FoxPro code:

loHttp = CREATEOBJECT("wwHttp")
loHttp.AddHeader("Authorization","Bearer " + lcToken)
lcJson = loHttp.Get(lcUrl)

All of this is designed to make it easier to create REST services that can authenticate without having to re-build a bunch of infrastructure. Instead this stuff re-uses what Web Connection already provides and exposes it to the newer REST service infrastructure with a couple of relative simple constructs you can add to your REST service with a few lines of code.

wwRestProcess.lRawResponse Helper Property

Speaking of REST services here's a small, but frequently used feature: There's now a Process.lRawResponse property that can be set to to .t. to return a raw, non-JSON response from a REST method. That functionality was always available via the JsonService.IsRawResponse, but it's a bit easier to set it on the local class instance.

So you can do the following in a REST method now:

FUNCTION ReturnPdf()

THIS.lRawResponse = .T.
Response.ContentType = "application/pdf"

 lcFilename = THIS.ResolvePath("~/policy.pdf") 

*** Send from memory - string/blob
lcFile = FILETOSTR(lcFilename)
Response.BinaryWrite( lcFile )

*** OR: Send from file
*!* Response.TransmitFile(lcFilename,"application/pdf")

ENDFUNC

wwDotnetBridge Improvements

There are a number of small tweaks to wwDotnetBridge as well in this release:

wwDotnetBridge.GetPropertyRaw() and ComArray.ItemRaw()
Overridden methods that allow for retrieval of property values in raw format that bypass the usual FoxPro fix-ups that ensure type safe values are returned to FoxPro. Useful in scenarios where the values are sometimes in ComValue or ComArray that can be accessed directly, or in scenarios where types have dual meaning (ie. char with raw number vs. string fix-up or Guid with raw binary vs. string fix-up).
ComArray.GetInstanceTypeName() and ComArray.GetItemTypename() helpers
Added a couple of helpers to the ComArray class to provide type information about the Array instance and it's client types for debugging or testing purposes. This can be useful to determine whether the .Instance member can be accessed directly via FoxPro code (many .NET collections cannot and require intermediary operations provided by ComArray or wwDotnetBridge).
wwDotnetBridge::DisposeInstance() to explicitly release Object Dependencies
This method explicitly release IDisposable object instances by calling .Dispose(). Since .Dispose() tends to be an overloaded virtual property you typically can't call it directly on a .NET reference instance, so this method helps making a direct call rather than calling InvokeMethod().
wwDotnetBridge: Improved support for Task Exception Handling
When making calls to .NET async or Task methods, wwDotnetBridge now does a better job of handling exceptions and returning the result in the OnError() callback. More errors are handled and error messages should be more consistent with the actual error (rather than a generic error and an innerException).

Json and REST Service Improvements in recent versions

wwJsonSerializer Deserialization Performance Improvements
Optimized the .NET parsing of the deserialized object graph for improved performance. Also fixed a few small issues that previously could result in naming conflicts that FoxPro couldn't deal with. Fixed a small issue with UTC dates when AssumeUtcDates (ie. passthrough as-is dates) is set.
wwJsonSerializer no longer uses PropertyExclusionList on EMPTY Object
When serializing EMPTY objects, or by association cursors and collections which internally use EMPTY objects, the PropertyExclusionList is not applied to properties. The list is meant to keep FoxPro default properties from polluting the output JSON, but EMPTY objects do not have any base properties, so the list is not necessary. This allows for creating properties with reserved FoxPro property names like Comment, Name, Classname etc.
Fix: wwJsonSerializer::AssumeUtcDates Output still converting to Local
Fixed issue that when this flag was set, it would not convert the inbound date from local to UTC but use the current date as UTC, but it would still convert the date back to local when deserializing. This change now leaves the deserialized date in the original UTC time, but returns it as a local FoxPro time (ie. the date is not adjusted for timezone) which was the original assumption of this flag. This was broken when we switched from FoxPro based parsing to .NET parsing using JSON.NET. This is a potentially breaking change if you used this obscure flag in your code.
wwJsonServiceClient CallService Url Fix up
You can now use a site relative URL by specifying a cServiceBaseUrl before calling CallService() which allows you to use site relative paths for the URL. You can use Urls like /authenticate which makes it easier to switch between different host sites. If the URL does not start with http:// or http://, the cServiceBaseUrl is prepended to the URL to create a full URL. This is useful if you switch between different sites such as running against different servers for dev, staging and production servers.
wwJsonServiceClient: Optionally capture Request and Response Data You can now optionally capture all request and response data via the lSaveRequestData flag. If set any POSTed JSON data will be capture in cRequestData and any result data is capture in cResponseData both of which are useful for debugging.
wwJsonServiceClient is abstracted into its own PRG File
wwJsonServiceClient now has migrated out of the wwJsonSerializer.prg file to its own wwJsonServiceClient.prg file. This is a minor breaking change - you'll need to make sure DO wwJsonServiceClient is called explicitly now to ensure the library is loaded along with all dependencies.
wwJsonServiceClient CallService Url Fix up
You can now use a site relative URL by specifying a cServiceBaseUrl before calling CallService() which allows you to use site relative paths for the URL. You can use Urls like /authenticate which makes it easier to switch between different host sites. If the URL does not start with http:// or http://, the cServiceBaseUrl is prepended to the URL to create a full URL. This is useful if you switch between different sites such as running against different servers for dev, staging and production servers.
Fix: wwJsonService UTF-8 Encoding/Decoding
Fixed inconsistencies in UTF-8 encoding by the service client. Now data sent is encoded and data received is decoded. Optional parameters allow disabling this auto en/decoding.

wwCache Improvements

wwCache is an old component in Web Connection that is internally used to cache certain bits of information in a local cursor. It's a great way to cache generated output or any string based value that you don't want to repeatedly regenerate or calculate out.

The class gains a few common method that were previously missing: Clear() that clears the cache and closes the underlying cache cursor to avoid excessive memo bloat and GetOrAddItem() that combines retrieving an existing value, or setting a new one into the cache in one step.

Note that in Web Connection the cache object is always available as Server.oCache:

PRIVATE pcToc

*** Retrieve a cached TOC or generate one
pcToc = Server.oCache.GetOrAddItem("Toc",GenerateToc(),3600)

*** pcToc can now be embedded into the template
Response.ExpandTemplate("~\toc.wcs")

Summary

Overall this major version release has no groundbreaking new features, but there are a number of significant and useful enhancements. I think the COM server features in particular are going to be very useful to those of you running busy sites on Web Connection.

As we go forward Web Connection will continue to do incremental updates of features and roll them into minor release updates, rather than providing big bang new versions with massive amount of changes that few will use due to feature overload ??.

As always with new releases, please, please report any issues you encounter on the message board.

Aloha,

+++ Rick ---

West Wind Client Tools 8.0 Release Notes

Rick Strahl — Thu, 30 May 2024 20:19:04 GMT

We've released v8.0 of the West Wind Client Tools. Although this is a major version update, this is not a huge release although there are a few noteworthy changes in the libraries that may require attention when upgrading. It's been 6+ years since the last release and there have been many improvements since so this release can be thought of as a version rollup release more than anything.

There are a few new features in this update however:

Refactored FTP Support for FTP, FTPS (FTP over TLS) and SFTP
New ZipFolder() functionality
Many improvements to wwDotnetBridge
Many functional and performance improvements in wwJsonSerializer

Upgrading

This is a major version upgrade, so this is a paid upgrade.

You can upgrade in the store:

If you purchased v7 on or after June 1st, 2023 (a year ago) you can upgrade for free until the end of the year, otherwise an upgrade is required for the new version (details on the upgrade link).

Refactored FTP Support

The FTP support in Web Connection and the Client Tools has been pretty creaky for years. The original FTP support was built ontop of the built-in Windows WinINET services. Unfortunately those services do not support secure FTP communication so we've always lacked support for FTPS (FTP over TLS). Some years ago I added the wwSFtp class to provide support SFtp (FTP over SSH) which mitigated some of the deficiencies, but FTPS tends to be pretty common as some popular servers like Filezilla Server use FTPS.

Long story short, in order to support FTPS I added a new wwFtpClient class that supports both plain FTP and FTPS in a more reliable manner. This new implementation is built ontop of a popular .NET FTP library that is more accessible, considerably faster, provides for logging and provides much better error handling in case of failures. The new wwFtpClient is considerably simpler than the old wwFTP class as it does away with all the WinINET related baggage. As such the model for wwFtpClient is simply:

Connect()
Run Ftp Commands
Close()

and those are the only interfaces supported. You can:

Download
Upload
DeleteFile
MoveFile
ListFiles
ChangeDirectory
CreateDirectory
RemoveDirectory
ExecuteCommand

The methods are simple and easier to use.

Along the same vein I've also replaced the wwSFTP class with wwSFtpClient which uses the exact same interface as wwFtpClient so both classes can be used nearly interchangeably. There some small differences in how connections can be assigned but otherwise both classes operate identically - the old classes were similar but not identical. The wwSFtpClient class uses the same SSH.NET .NET library as before, although it's been rev'd to the latest version.

The old wwFtp and wwSFtp classes are still available in the OldFiles folder and they continue to work, but the recommendation is to update to the new classes if possible as they are easier to use and more reliable with more supported types of connections (for wwFtpClient).

ZipFolder() and UnzipFolder()

ZipFolder() is a new library function in wwAPI that provides zipping functionality from a folder using the built in Windows zip services, meaning there are no external dependencies on additional libraries. These functions use .NET to handle the Zipping interface, which removes the dependency on the old DynaZip dlls.

The old ZipFiles() and UnZipFiles() functions are still available, but they continue to require the dzip/dunzip/zlib1 dlls.

wwDotnet Bridge Improvements

The last few release of wwDotnetBridge have seen a number of improvements on how result values are passed back to .NET fixing up more types so that they work in .NET. There has been a lot of work around Collection access related to the ComArray class that is returned for lists and collections. The new AddItem() method makes it easy to add items to a collection effectively and AddDictionaryItem() makes it easy to added to key and value collections. There are also some improvements on how ComArray .NET instances are managed and can be accessed that results in additional use cases that did not previously work in some scenarios.

Additionally there's been some work to clean up how exceptions are handled and returned in error messages which should result in cleaner error messages without COM artifacts gunking up the message text. We've also fixed exception handling for Task Async operations - exceptions are now returned from failed task operations, rather than the generic failure that was returned prior.

JSON and REST Service Calls

The wwJsonSerializer is probably one of the more popular Client Tools components and it's getting a few new features in this release. There have been many tweaks in the last couple releases. One has been to optimize EMPTY object serialization by skipping the exclusion list which is meant to prevent FoxPro base properties from rendering which can improve performance significantly on large lists. There are now options for how dates are handled either as local or UTC dates based on the incoming data's date formatting.

The JsonSerivceClient gets the ability to capture request and response data optionally which can be useful for debugging or logging/auditing.

Breaking Changes? No Except for FTP

Although this is a major version update, there are no breaking changes other than the new FTP classes. And for those you can continue to use the older wwFtp and wwSFtp classes if necessary.

You will have to make sure to update your DLL dependencies however, so make sure you update:

wwipstuff.dll
wwDotnetBridge.dll
Newtonsoft.Json.dll
FluentFtp.dll (for wwFtpClient)
Renci.SshNet.dll (for wwSFtpClient)

+++ Rick ---

wwDotnetBridge and Loading Native Dependencies for .NET Assemblies

Rick Strahl — Sat, 23 Mar 2024 23:12:11 GMT

When using wwDotnetBridge to access .NET components you may run into .NET components that have native binary dependencies. When I say 'native' here I mean, non-.NET Win32/C++ dependencies that are generally not following the same assembly loading rules as the .NET host.

##AD##

An Example: NHunspell, Spellchecking and Word Suggestions

Just for context, this is the NHunspell Spell checking component I highlighted in a Southwest FoxSession all the way back in 2016. This library is based on the popular HUnspell native library, for which NHUnspell is basically a .NET wrapper. The .NET wrapper just makes the appropriate interop calls to native C++ library.

I created a FoxPro class around the .NET component using wwDotnetBridge:

*************************************************************
DEFINE CLASS HunspellChecker AS Custom
*************************************************************
*: Author: Rick Strahl
*:         (c) West Wind Technologies, 2015
*:Contact: http://www.west-wind.com
*:Created: 08/07/15
*************************************************************
oBridge = null
oSpell = null
cLanguage = "en_US"
cDictionaryFolder = "" && root

************************************************************************
*  init
****************************************
FUNCTION init(lcLang, lcDictFolder)

IF EMPTY(lcLang)
   lcLang = this.cLanguage
ENDIF
IF EMPTY(lcDictFolder)
   lcDictFolder = this.cDictionaryFolder
ENDIF
   
this.oBridge = GetwwDotnetBridge()
IF ISNULL(this.oBridge)
      ERROR "Failed to load HUnspell: " + this.oBridge.cErrorMsg
ENDIF

* ? this.oBridge.GetDotnetVersion()

IF !this.oBridge.LoadAssembly("NHunspell.dll")
  ERROR "Failed to load HUnspell: " + this.oBridge.cErrorMsg
ENDIF

IF !EMPTY(lcDictFolder)
	lcDictFolder = ADDBS(lcDictFolder)
ELSE
    lcDictFolder = ""
ENDIF

this.oSpell = this.oBridge.CreateInstance("NHunspell.Hunspell",;
                                  lcDictFolder + lcLang + ".aff",;
                                  lcDictFolder + lcLang + ".dic")
                                  
IF VARTYPE(this.oSpell) # "O"
   ERROR "Failed to load HUnspell: " + this.oBridge.cErrorMsg
ENDIF  
                                  
IF FILE(lcDictFolder + lcLang + "_custom.txt")
  lcFile = FILETOSTR(lcDictFolder + lcLang + "_custom.txt")
  lcFile = STRTRAN(lcFile,CHR(13) + CHR(10),CHR(10))
  lcFile = STRTRAN(lcFile,CHR(13),CHR(10))
  LOCAL ARRAY laLines[1]
  LOCAL lnX, lnLine
  lnLines = ALINES(laLines,lcFile,1 + 4,CHR(10))
  FOR lnX = 1 TO lnLines
      this.oSpell.Add(laLines[lnx])            
  ENDFOR
ENDIF
                                  
IF ISNULL(this.oSpell)
  ERROR "Failed to load HUnspell: " + this.oBridge.cErrorMsg
ENDIF

ENDFUNC
*   init

************************************************************************
*  Spell
****************************************
***  Function: Checks to see if a word is a known word in the dictionary
************************************************************************
FUNCTION Spell(lcWord)

IF ISNULL(lcWord) OR EMPTY(lcWord) OR LEN(lcWord) = 1
   RETURN .T.
ENDIF

RETURN this.oSpell.Spell(lcWord)
ENDFUNC
*   Spell

************************************************************************
*  Suggest
****************************************
***  Function: Gives back a collection of word suggestions for 
***            the passed in word
************************************************************************
FUNCTION Suggest(lcWord)
LOCAL loWords, lnx

loCol = CREATEOBJECT("collection")
loWords = this.obridge.InvokeMethod(this.oSpell,"Suggest",lcWord)
? lowords
? this.oBridge.cErrorMsg

lnCount = this.oBridge.GetProperty(loWords,"Count")
? this.oBridge.cErrormsg
?  "Count: " + TRANSFORM(lnCount)


FOR lnX = 0 TO lnCount -1
    lcWord =  loWords.Item(lnX)
    loCol.Add( lcWord )
ENDFOR


RETURN loCol
ENDFUNC
*   Suggest


************************************************************************
*  AddWordToDictionary
****************************************
FUNCTION AddWordToDictionary(lcWord, lcLang)

lcFile = "editors\" + lcLang + "_custom.txt"
AppendToFile(lcWord + CHR(13) + CHR(10),lcFile)
this.oSpell.Add(lcWord)

ENDFUNC
*   AddWordToDictionary

************************************************************************
*  Destroy
****************************************
FUNCTION Destroy()

*** MUST dispose to release memory for spell checker
this.oSpell.Dispose()
this.oSpell = null

ENDFUNC
*   Destroy

ENDDEFINE
*EOC HunspellChecker

To use it you just instantiate the class and pass in a dictionary, then check for spelling or get suggestions:

loSpell = CREATEOBJECT("HunspellChecker","en_US",".\Editors")   
? loSpell.Spell("Testing")
? loSpell.Spell("Tesdting")   

lcWord = "aren'tt"
? "Suggest Testding"
loSug = loSpell.Suggest(lcWord)
? loSug.Count
FOR EACH lcWord in loSug
   ? lcWord
ENDFOR
loSpell = null

loSpell = CREATEOBJECT("HunspellChecker","de_DE",".\Editors")
? loSpell.Spell("Zahn")
? loSpell.Spell("ZÃ¤hne") 
? loSpell.Spell("lÃ¤uft") 
loSug = loSpell.Suggest("ZÃ¤hjne")
FOR EACH lcWord in loSug
   ? lcWord
ENDFOR
      
? loSug.Count
loSpell = null

I use this library both in Markdown Monster (in .NET) and Html Help Builder (FoxPro) to provide on the fly spell checkiing inside of Markdown documents. The above methods provide both for the error highligghting as well as the suggestions that are popped up in the editor.

Surprisingly, this is very fast even accounting for interop between JavaScript and FoxPro and FoxPro to .NET!

This is just to give you some context of a library that has a native dependency (and because I know some of you would ask about the functionality ??)

Library and Dependencies: Watch Load Location

So NHunspell has a .NET assembly NHUnspell.dll and a native dependency for the underlying Win32 32 bit hunspellx86.dll (or hunspell.dll for the 64bit version).

So the two file dependencies for the .NET component are:

NHunspell.dll (.NET assembly)
HUnspellx86.dll (Win32 native dll)

Standard.NET Assembly Loading Behavior

Natively .NET dependencies resolve only out of the EXE's startup path or an optional PrivateBin path that can be assigned in app.config or through the hosting runtime instantiation.

For a FoxPro application that would mean 1 of 2 things:

Your EXE's startup folder when running the EXE
VFP9.exe's startup folder

wwDotnetBridge Assembly Loading Behavior

wwDotnetBridge tries to be a little more helpful and basically tries to resolve assembly paths for you if you explicitly load assemblies via LoadAssembly():

loBridge = GetwwDotnetBridge()

*** Looks in current and FoxPro Path
loBridge.LoadAssembly("NHUnspell.dll")

If you specify a non-pathed DLL name, wwDotnetBridge does FULLPATH(lcAssembly) on it, which resolves to the current path or anything along the FoxPro path to eventually provide an absolute path to the DLL. .NET by default looks for other assemblies in both the startup path and the location an explicitly loaded assembly is loaded from. IOW, any child dependencies automatically inherit the path of the parent for trying to find assemblies.

Alternately you can also specify an explicit path directly:

loBridge.LoadASsembly("c:\libraries\bin\NHUnspell.dll")

All this is great and predictable, but... it only applies to .NET assemblies, not any natively loaded assemblies.

Natively loaded Dependencies

If a .NET component has a native dependency as NHunspell has in the form of hunspellx86.dll that native DLL either has to be explicitly discovered and found by the .NET component, or it uses the default path resolution.

Default Native Path Resolution

The default path resolution for a native dependency is that it is loaded only out of the launching EXE's startup folder.

Custom Native Path Resolution

Some libraries use custom path resolution which set up their own folders and EXPLICITLY load out of that folder. For example, the popular LibGit2Sharp library uses a custom runtime/win-x86 folder where win-x86 is the platform you are using (x86 for FoxPro 32 bit).

The best way to see where things are expected is to create a .NET project and install the NuGet package into it, and then see exactly where files are placed. Then use the same 'offset' in your own project: If it dumps it into the root, use the same folder as your EXE, if there's a runtime folder duplicate that structure and put the DLL there.

NUnspell Loading

NHUnspell uses default native path resolution so if you are going to use the functionality both in your deployed application and in the FoxPro IDE you need to put the native hunspellx86.dll in two places:

Your EXE's startup folder
VFP9.exe startup folder if you're running in the Fox IDE

How this can bite you

I'm writing about this because this bit me hard today. I recently set up a new laptop and ended up reinstalling all of my applications including Visual FoxPro. I ran Help Builder which was installed using its installer from Chocolatey and it ran fine. Then I fired it up in the FoxPro IDE and it kept crashing on the spell library with .oSpell not found when running from within VFP.

Of course I didn't immediately remember that the spell checking logic has a native dependency so I started trying to track down the error. Only fails at dev time, not at deployed runtime. Weird, huh? Not with what we know now, but 3 years from now???

The problem is that I reinstalled VFP 9 and of course did not remember to install the hunspellx86.dll in the VFP IDE folder. Once I moved the DLL into the VFP9 install folder all is well.

To be clear though - my deployed application that runs the EXE still worked because the installer copies the hunspellx86.dll into the install directory - no issue there, but the VFP install is tricky because you're not going to see anything wrong until you run your specialized application a long time after installation.

Make notes, and hopefully you'll remember to read them... I will and probably won't remember. Ha!

##AD##

Summary

The jist of this post is that when you use a library with native dependencies make sure you understand the native libraries have different load behavior than the .NET libraries, with the default behavior being that it will load out of the startup EXE's startup folder. And remember that for FoxPro applications you typically have two root EXEs that you need to worry about for development in the IDE using VFP9.exe and for development with your own compiled EXE.

Rick Strahl's FoxPro and Web Connection Weblog

What is CORS and how to set it up in West Wind Web Connection

Web Browser Only Protocol but implemented by the Server

CORS doesn't fire on localhost

The CORS Protocol

Pre-flight OPTIONS Request

In-flight Request

CORS Failure and Success Responses

Beware of Access-Control-Allow-Origin: *

CORS in Web Connection

Original Origins

Methods

Headers

Allow Credentials

Summary

Web Connection 8.4 Release Post

Bug Fixes

Fix User Authentication Session Cookie Bug

Fix: wwHttp Multipart Form Data Content Type not getting set

Missing JsonService Variable in wwRestProcess Process Methods

New and Improved Features

wwDotnetBridge: Unblock all DLLs loaded

New Offline Documentation Viewer

Summary

Creating and Debugging .NET Assemblies for wwDotnetBridge and Visual FoxPro

Creating your own .NET Components

Creating a new Project 'by hand'

Shutting down Visual FoxPro to Unload .NET Assembly

Opening the Project in Visual Studio

Debugging

Summary

Resources

FoxPro Running on a Windows ARM Device

FoxPro and Web Connection

Everything works - except SQL Server!

Just about everything works!

.NET Applications - Just Run Natively!

The one thing that was problematic: SQL Server

Summary

Web Connection 8.1 Release Post

Support for greater than 16mb Web Response Output

Related wwPageResponse and wwUtils Changes

Improvements to COM Server Handling

Improved wwDotnetCoreBridge Stability

Breaking Change: Updated Log Format

Summary

Making Web Connection Work with Response Output Greater than 16mb

Making >16mb Output work in Web Connection

Working with >16mb Strings

Use >16mb Content with Care

Reducing Output Size Significantly with GZipCompression

Summary

wwDotnetBridge Revisited: An updated look at FoxPro .NET Interop

What we cover

.NET History: .NET Framework to .NET Core

.NET and FoxPro

Stick to .NET Framework

Why .NET for FoxPro?

What is wwDotnetBridge?

A quick Primer

Setting up wwDotnetBridge

Loading DLLs from Network Locations: Configuration required

Loading wwDotnetBridge and Loading your first .NET Library

Loading Assemblies and Creating an Instance

Direct Invocation of Members

Proxy Invocation for Problem Types and Helpers

How does wwDotnetBridge Work

A .NET Loader

wwDotnetBridge Loader

Direct Member Access is via COM

Indirect Member Access via InvokeMethod(), GetProperty() and SetProperty()

wwDotnetBridge Proxy Type Wrappers: ComArray and ComValue

Working with .NET From FoxPro: Finding what you need!

Figuring out what Assemblies (DLLs) to Provide

Raw DLL Distribution

NuGet Package Distribution

Make sure Dependencies are provided

Finding DLLs: Unpacking NuGet Packages and their Dependencies using a .NET Project

dotnet new doesn't work for .NET Framework Projects

Use a Disassembler Tool to discover .NET Types and Members

`dotnet new` doesn't work for .NET Framework Projects