Debugging Managed COBOL Applications Running in Containers

Note: The information in this topic applies only to debugging managed COBOL applications which are running in Docker containers. This feature is only available if are using Visual Studio 2017 (or later).

Most of the information in this topic is also included elsewhere in the documentation in topics that describe debugging containerized COBOL applications in general. It is summarized here for your convenience.

Including Support for Managed COBOL in an Image

The ability to debug a managed COBOL application running in a container relies on remote debugging functionality provided by Microsoft Remote Tools, so when you are building an image that will be used for this purpose you must ensure that the image includes the following additional files:

  • The remote debugger, which is part of Microsoft's Remote Tools. To use the remote debugger in an image you need to perform the following steps:
    1. Copy the installer for the Remote Tools (VS_RemoteTools.exe) into the image's filesystem and install it.

      If you do not already have VS_RemoteTools.exe you can download it from the Microsoft site (see Microsoft: Remote Debugging a C# or Visual Basic project in Visual Studio) or use a Powershell command as shown in the bld.bat file for the Build_HelloWorld Docker demonstration.

    2. Update the PATH to include the folder where the Remote Tools were installed.
    3. Run the remote debugger.

    Typical commands that you could include in a Dockerfile to perform these steps are as follows:

    COPY VS_RemoteTools.exe "${APPDIR}\\"
    RUN VS_RemoteTools.exe /install /quiet /norestart && \
        del VS_RemoteTools.exe && \
        setx /M PATH "%PATH%;C:\\Program Files\\Microsoft Visual Studio 15.0\\Common7\\IDE\\Remote Debugger\\x64"
    ...
    CMD msvsmon.exe /nostatus /silent /noauth /anyuser /nosecuritywarn
    

    For more information on Microsoft's remote debugging see Microsoft: Remote Debugging a C# or Visual Basic project in Visual Studio. Although that article refers to C# and Visual Basic, those languages use remote debugging in much the same way as does managed COBOL.

  • The file MicroFocus.COBOL.ExpressionEvaluator.Remote.dll. This file is supplied with Visual COBOL and by default is installed in %Program Files%\Microsoft Visual Studio\2017\Professional\Common 7\IDE\Remote Debugger\x86 or %Program Files%\Microsoft Visual Studio\2017\Professional\Common 7\IDE\Remote Debugger\x64. You need to copy the relevant file into the image's filesystem, into the folder where the remote debugger is installed.

    A typical command that you could include in a Dockerfile to do this is as follows:

    COPY [ "%Program Files%\Microsoft Visual Studio\2017\Professional\Common 7\IDE\Remote Debugger\x64\MicroFocus.COBOL.ExpressionEvaluator.Remote.dll" , "\Program Files\Microsoft
    Visual Studio 15.0\Common7\IDE\Remote Debugger\x64" ]

Micro Focus recommends that you install the managed COBOL support only into images containing managed COBOL applications that you need to debug. Doing this avoids installing the support into images where it would not be used but would still take up disk space and other resources.

Alternatively you could create a managed COBOL-specific version of the Visual COBOL base image. To do this you would use the Visual COBOL base image as a starting point and add the managed COBOL support into it. Using this approach would give you one Visual COBOL image to use for debugging native COBOL applications and a different Visual COBOL image to use for debugging managed COBOL applications.

Starting an Image Containing a Managed COBOL Application to be Debugged

When starting an image containing a managed COBOL application to be debugged you do the same as you would as if the application was native but with the following differences:

  • Debugging managed COBOL does not use the Micro Focus cobdebugremote process, so instead of starting cobdebugremote, you need to invoke the remote debugger (msvsmon.exe).

    e.g. Default entrypoint in container, overriding entrypoint on Docker Run, triggering via Docker exec etc.

  • The folder structure of the managed COBOL application's executable and symbols .idy files must be the same on your local machines and the image's filesystem.

    The easiest way to achieve this is to volume mount the top level folder which you could do with a docker run command option such as the following:

    -v C:\ManagedCOBOLApp:C:\ManagedCOBOLApp

To start debugging a managed COBOL application that is already running in a container

When using the Attach to Process option to connect to a container that is running a managed COBOL application, the process is the same as for when the application is native but with the following difference:

  • In the Connection type field, specify Remote (no authentication) (if you invoked the remote debugger (msvsmon.exe) with the "/noauth" flag) or Default (if you are using authentication).