If you use .NET with OpenEdge, you may eventually need to upgrade to a newer .NET version. This topic describes the steps required to upgrade. They apply to both Windows and Linux.

Note: These steps impact all products installed into the OpenEdge installation location that make use of .NET. This includes Progress Application Server (PAS) for OpenEdge sessions, regular PROWIN (desktop) sessions, character mode client, and Progress Developer Studio for OpenEdge.
  1. Download and install the desired .NET version — You can use either the .NET Runtime or the .NET SDK. You can download .NET from https://dotnet.microsoft.com/en-us/.
  2. Update runtimeconfig.json:
    1. Using a text editor, open $DLC/bin/Progress.clrbridge.netcore.runtimeconfig.json.
    2. Change the tfm (target framework moniker) entry to the new version. For example, change the value of tfm from "net6.0" to "net8.0" to upgrade to .NET 8. For more information on target frameworks, see the Microsoft documentation.
    3. Change the version references. For example, change all the version values from "6.0.0" to "8.0.0".
    4. Save the file. The following example shows what the Progress.clrbridge.netcore.runtimeconfig.json file looks like for .NET 8:
      {
  "runtimeOptions": {
    "tfm": "net8.0",
    "frameworks": [
      {
        "name": "Microsoft.NETCore.App",
        "version": "8.0.0"
      },
      {
        "name": "Microsoft.WindowsDesktop.App",
        "version": "8.0.0"
      }
    ],
    "configProperties": {
      "System.Reflection.Metadata.MetadataUpdater.IsSupported": false
    }
  }
}
    Note: There are other properties that can be added to his file. Read the Microsoft documentation for additional details.
  3. Update .NET assemblies — Locate and replace any .NET assemblies that are incompatible with the new .NET version you just installed. Make sure to update the assemblies.xml file(s) for your OpenEdge application.
  4. Recompile your application — Recompile your OpenEdge application after updating the assemblies so the r-code has updated assembly references.
  5. Restart your application — Restart your OpenEdge application using the -clrnetcore startup parameter.
Note: To go back to the previous version of .NET, restore the tfm and versions in runtimeconfig.json to what they were previously, update the assemblies (if required), recompile, and restart your application.

Troubleshooting notes

  • If the tfm and frameworks property values are not correct, you get an error message displayed on the screen indicating that the requested version of .NET is not available. Make sure the required version of .NET is installed, and review the contents of the runtimeconfig.json file to ensure they match. If you think you have the right version of .NET installed, you need to make sure that OpenEdge can locate it. The location where .NET is loaded from depends on the operating system. See https://github.com/dotnet/designs/blob/main/accepted/2020/install-locations.md for more detail. You can turn on .NET logging if needed to assist with troubleshooting.
  • You can use any patch release of .NET, but the latest is preferable. .NET automatically picks the most recent installed version that is greater than or equal to the version specified in runtimeconfig.json. To bypass this behavior and specify a specific patch version, see the Microsoft documentation for additional properties you can set to do this.