To package Micro Focus COBOL assemblies with a .NET application

Visual COBOL ships with a number of NuGet packages that your .NET COBOL projects link to. Unless specified otherwise, new .NET COBOL projects link to the MicroFocus.COBOL.Runtime.Core package which provides the minimum required functionality. You need to add any other packages manually, if your application requires more than the core functionality.

.NET projects created with release 8.0 and earlier linked to the MicroFocus.COBOL.Runtime NuGet package. This provides all the required Micro Focus COBOL assemblies for your applications to run under .NET - for example, the Run-Time System components, different File Handlers, etc. There are some upgrade considerations if you want to work with existing projects in this release.

Specify NuGet packages to include in a .NET project from the project's properties inside Visual Studio

You can specify the NuGet packages to use with your .NET project as follows:

  1. Open your .NET COBOL application in Visual Studio.
  2. In Solution Explorer, expand the Packages node under Dependencies.

    As a minimum, .NET COBOL projects link to the MicroFocus.COBOL.Runtime.Core NuGet package. There is a dependency on the complete MicroFocus.COBOL.Runtime package, if you selected this when the project was created in 10.0.

  3. Open the project's properties, and click the Application tab.
  4. Note the Use COBOL Runtime Metapackage option.

    When this is checked, the complete set of Micro Focus COBOL functionality available in the MicroFocus.COBOL.Runtime NuGet package is added to your project. This option is for compatibility purposes. You do not need this if your applications only use some of the functionality, and you want to keep the application's size smaller.

  5. Click Advanced Package Selection.
  6. Specify a file handler option, and any additional features as necessary for your application. See Application Properties Page for details.
  7. Click OK.
  8. Save your changes.

Add any specific NuGet packages to .NET COBOL projects outside of the IDE

To add any Micro Focus COBOL NuGet packages to a .NET project in code view:

  1. Edit the project file in a text editor.
  2. Depending on what functionality your project needs, use the following syntax to add individual NuGet package in the PropertyGroup section:
    • To add COBOL Accept/Display package, add: <UseCOBOLADIS>True</UseCOBOLADIS>
    • To add JSON support, add <UseCOBOLJSON>True</UseCOBOLJSON>
    • To add SLR support, add <UseCOBOLSLR>True</UseCOBOLSLR>
    • To add XML support, add <UseCOBOLXML>True</UseCOBOLXML>
    • To add a File Handler, add <UseCOBOLFileHandler>value</UseCOBOLFileHandler>, where value is one of:
      None
      Default. Specifies that the project does not use a file handler.
      Native
      Adds the native file handler.
      Managed
      Adds the .NET file handler. In addition, if the project is set to compile as verifiable code (ILVERIFY or IDE setting), the 'Safe' managed file handler is used.
    • Alternatively, to add the MicroFocus.COBOL.Runtime metapackage for the full functionality, specify: <DisableCOBOLRuntimeMetaPackage>False</DisableCOBOLRuntimeMetaPackage>.
  3. Save your changes.

Available NuGet Packages

These are the Micro Focus COBOL NuGet packages available to you to use with your .NET applications. They are stored in <InstallDir>\NuGetPackages:

  • MicroFocus.COBOL.Runtime.Core.4.100.0.nupkg - a cut-down run-time package containing the minimal set of assemblies required by the .NET COBOL programs. Any new .NET projects include this as a minimum.
  • MicroFocus.COBOL.Runtime.4.100.0.nupkg - a metapackage referencing all other packages. It exists for backwards compatibility.
  • MicroFocus.COBOL.FileHandler.4.100.0.nupkg - contains the assemblies required for the .NET COBOL file handler. Use this when your .NET COBOL programs contain the CALLFH"EXTFH" directive.
  • MicroFocus.COBOL.FileHandler.Native.4.100.0.nupkg - contains the assemblies and supporting native runtime libraries required for the native file handler. Use this when your .NET COBOL programs contain the CALLFH"NATIVEFH" directive.
  • MicroFocus.COBOL.FileHandler.Safe.4.100.0.nupkg - contains the assemblies required for the .NET COBOL file handler compiled in verifiable mode (ILVERIFY). Use this when your .NET COBOL programs contain both ILVERIFY and the CALLFH"EXTFH" directives and/or to support deployment as SQL Server stored procedures or ASP.NET applications hosted in partial trust modes.
  • MicroFocus.COBOL.MFUNIT.8.100.0.nupkg - contains the assemblies required for Micro Focus Unit Testing Framework support.
  • MicroFocus.COBOL.Runtime.ADIS.4.100.0.nupkg - contains the assemblies supporting execution of extended ACCEPT/DISPLAY statements. Equivalent to setting <UseCOBOLADIS>true</UseCOBOLADIS> in the PropertyGroup section of the project file.
  • MicroFocus.COBOL.Runtime.JSON.4.100.0.nupkg - contains the assemblies supporting execution of JSON GENERATE, and JSON PARSE statements. Equivalent to setting <UseCOBOLJSON>true</UseCOBOLJSON> in the PropertyGroup section of the project file
  • MicroFocus.COBOL.Runtime.XML.4.100.0.nupkg - contains the assemblies supporting execution of XML GENERATE, XML PARSE, JSON GENERATE, and JSON PARSE statements. Equivalent to setting <UseCOBOLXML>true</UseCOBOLXML> in the PropertyGroup section of the project file
  • MicroFocus.COBOL.SqlCLR.Runtime.4.100.0.nupkg - contains the assemblies required for SQL support. Equivalent to setting <UseCOBOLSLR>true</UseCOBOLSLR> in the PropertyGroup section of the project file

Native and .NET File Handler

By default, COBOL applications in .NET projects use the native file handler for their file handling operations. In order for the native file handling functionality to be available when the project is deployed and run, when you publish a .NET project the published files include the required native run-time system and file handler. These are part of the MicroFocus.COBOL.Runtime package which includes all the Micro Focus COBOL functionality. If your application does not include the complete NuGet package, you need to add any required individual smaller packages as listed earlier.

If you will be debugging a local .NET application on Windows where the main program is not COBOL, for example the main program is C#, you must ensure that an appropriate file handler is used. Failure to do so will result in run-time system error COBRT198 ("Load failure") on the first COBOL file I/O statement.

By default, the 32-bit native version of the file handler will be available. For this to be used by your application you need to make sure the project for the main program is built to target the x86 platform.

Alternatively, to avoid any dependency on the native run-time system you can use the .NET file handler. You can switch a .NET project to use the .NET file handler rather than the native file handler by specifying the directives CALLFH(EXTFH) and CALLSORT(EXTSM) in the project.

SQL Support

See SQL Support for .NET Projects for details on how to add SQL support to your projects.