Upgrading existing .NET COBOL project files

Upgrading existing projects to release 10.0

Release 10.0 comes with support for .NET 8 and with newer versions of the Visual COBOL SDK and the NuGet packages. Earlier versions of the .NET are not supported.

In order for your existing .NET COBOL projects to build, you need to update the Target framework to .NET 8 from the Application page in the project's properties.

Upgrading existing projects in release 9.0

The 9.0 release introduces the following changes:

NuGet package changes - the 9.0 release installs several NuGet packages each of which contains the assemblies for a specific Visual COBOL functionality. New .NET projects, as well as existing projects you edit or build in 9.0 are linked to a core package, MicroFocus.COBOL.Runtime.Core, that includes the basic functionality for the projects. You need to add any additional packages (such as a specific file handler, COBOL Accept/Display etc.) manually to the projects.
Building existing .NET COBOL projects created prior to 9.0 might result in build errors. To ensure compatibility for older projects, 9.0 also provides a MicroFocus.COBOL.Runtime metapackage. You can either enable this or add any required new NuGet packages manually to them.

See To package Micro Focus assemblies with a .NET application for details.
Newer SDK version - the Visual COBOL SDK version has changed from version 2.0 in release 8.0 to version 2.1.
Updating the SDK means that projects will reference the MicroFocus.COBOL.Runtime.Core package. This is how you can avoid receiving any build errors due to the change:
- If you open a .NET project created with an earlier release, Visual Studio displays an information bar with a message that the global.json file is targeting an earlier version of the required build SDK. To be able to edit the project in this release, click Update and Reload Solution which updates the SDK. You then need to add any required NuGet packages beyond the core functionality manually to the project or enable the MicroFocus.COBOL.Runtime metapackage. See To package Micro Focus assemblies with a .NET application .
- If you compile any existing projects from the command line, you might get build errors as the SDK links the project to MicroFocus.COBOL.Runtime.Core. You can switch off the new behavior and avoid any build errors this in one of the following ways:
  - Specify the environment variable DisableCOBOLRuntimeMetapackage=false.
  - Add this environment variable when you compile at the command line: msbuild.exe /p:DisableCOBOLRuntimeMetapackage=false.
  - Edit the project file in a text editor, and add <DisableCOBOLRuntimeMetapackage>false</DisableCOBOLRuntimeMetapackage> to the PropertyGroup section. This is equivalent to checking Use COBOL Runtime Metapackage on the Application properties page of the project inside Visual Studio.

Upgrading to releases 8.0 and later

Visual Studio 2022 requires that the global.json file of .NET 6 projects is placed at the directory level of the solution file in order for the project to successfully open and build. In previous versions of Visual Studio, the file could be located in subfolders of the solution such as in the project folder.

This can affect existing .NET Core 3.1 COBOL projects that you upgrade from a prior release if the global.json file is not at the directory level of the solution file. It also affects .NET 6 COBOL projects that you add to an existing solution.

In these cases, you might receive the following error message if building from the MSBuild command line, or in the Output window inside Visual Studio if the project fails to load:

"The SDK 'MicroFocus.Sdk' specified could not be found"

To work around this issue, you need to move the global.json file to the directory level of the solution file.

New .NET 6 COBOL solutions and projects created with Visual Studio 2022 create the global.json file in the required location.

Upgrading from releases earlier than 7.0

You cannot use dotnet commands to work with .NET projects (previously .NET Core projects) that were created using a version of Visual COBOL before 7.0. Instead, you can either continue to use such projects using the Visual Studio IDE and the msbuild command, or upgrade them in order to be able to use the dotnet commands.

To upgrade a pre-7.0 project file so that you can use the project with dotnet commands you need to do the following:

Modify the project (.cblproj) file as follows:
1. Change the first line from:
```
<Project Sdk="Microsoft.NET.Sdk">
```
  to:
```
<Project Sdk="MicroFocus.Sdk"
```
2. Delete the two lines that start with the following:
```
<LanguageTargets
```
Create a global.json file in the project folder to define the version of the Micro Focus project SDK to use. For example:
```
{
    "msbuild-sdks": {
        "MicroFocus.Sdk": "1.0.16"
    }
}
```
For more information on modifying your .cblproj and global.json files to do this, see Microsoft: How to: Use MSBuild project SDKs.