.NET Core

Red Hat OpenShift implements .NET Core support via a source-to-image (S2I) builder. In this article, we’ll take a closer look at how you can use that builder directly. Using S2I, you can build .NET Core application images without having to write custom build scripts or Dockerfiles. This can be useful on your development machine or as part of a CI/CD pipeline.

Containers for your builds

Container images provide an efficient mechanism to deploy self-contained applications in a portable way across clouds and OS distributions.

By building the application images themselves using a builder image, the application images can be built in a portable, reproducible way.

S2I is a toolkit for building reproducible application images. S2I uses builder images to produce application images from source code or pre-compiled applications.

application source/        +-------+
prebuilt application  +--> |  s2i  | +-->  application image
                        builder image

On Fedora and Red Hat Enterprise Linux (RHEL), you can obtain S2I by installing the source-to-image package (yum install source-to-image). If you are using another OS, including Windows and macOS, you can download S2I from github.com/openshift/source-to-image/releases. You’ll also need to install docker and git, which are used by s2i.

.NET Core builder images

A builder image is available for each .NET Core version. These images are built from the Dockerfiles at github.com/redhat-developer/s2i-dotnetcore.

For .NET Core 2.1, these images are available as follows:

OS base Image Type Image Name
RHEL 7 Runtime registry.redhat.io/dotnet/dotnet-21-runtime-rhel7:2.1
RHEL 7 SDK registry.redhat.io/dotnet/dotnet-21-rhel7:2.1
CentOS 7 Runtime registry.centos.org/dotnet/dotnet-21-runtime-centos7:latest
CentOS 7 SDK registry.centos.org/dotnet/dotnet-21-centos7:latest

If you are looking for a different .NET Core version, you can check the Red Hat Container Catalog or the CentOS Container Registry.

To use the RHEL 7 images, you need a Red Hat subscription. For development, you can use the free development subscription. Use the docker login registry.redhat.io command to configure your credentials.

Building images

The sections below describe three ways you can build your images.

Building an application image from a git repository

As our first, example, we’ll build an application image named mywebapp for the ASP.NET Core application at github.com/redhat-developer/s2i-dotnetcore-ex.

$ s2i build https://github.com/redhat-developer/s2i-dotnetcore-ex registry.redhat.io/dotnet/dotnet-21-rhel7:2.1 mywebapp -r dotnetcore-2.1 -e DOTNET_STARTUP_PROJECT=app -p always

When we run this command, we’ll see s2i check out the sources and build the .NET Core application image. When the command finishes, we can run the newly created image:

$ docker run --rm -p 8080:8080 mywebapp

Let’s look at the parameters we’ve passed to the s2i command:

Parameter Description
registry.redhat.io/dotnet-21-rhel7:2.1 S2I builder image
https://.../s2i-dotnetcore-ex The git repository
-r dotnetcore-2.1 Branch in the repository
-e DOTNET_STARTUP_PROJECT=app Folder in the repository that contains the application csproj file
-p always Always pull the latest builder image

The -e DOTNET_STARTUP_PROJECT is an environment variable passed to the S2I builder. The builder supports a number of environment variables that allow you to customize its behavior. See the environment variables documentation for a complete list.

Building an application image from local sources

The source parameter for the s2i command can also refer to a local folder that contains the source code. In the following example, we clone the repository locally and check out the appropriate branch into the s2i-dotnetcore-ex folder. Then we build from that local folder.

$ git clone -b dotnetcore-2.1 https://github.com/redhat-developer/s2i-dotnetcore-ex
$ s2i build s2i-dotnetcore-ex registry.redhat.io/dotnet/dotnet-21-rhel7:2.1 mywebapp -r dotnetcore-2.1 -e DOTNET_STARTUP_PROJECT=app -p always

We can run the image using the same docker run command as before.

Building an application image from a pre-built application

The .NET Core builder can also be used to build an application image from a pre-built application.

To explore this, we first publish the s2i-dotnetcore-ex application. To do that, you need to install a .NET SDK on your system (RHEL7/CentOS7, Fedora, other).

$ git clone -b dotnetcore-2.1 https://github.com/redhat-developer/s2i-dotnetcore-ex
$ cd s2i-dotnetcore-ex/app
$ dotnet publish -c Release /p:MicrosoftNETPlatformLibrary=Microsoft.NETCore.App

We are specifying the MicrosoftNETPlatformLibrary parameter to make the published application contain the ASP.NET Core shared framework assemblies. This is needed because the images don’t contain the shared framework.

To create the image, we pass the publish folder as the source parameter of the s2i build command. We can use the SDK builder images like before, but since the application is already built, we can use the smaller runtime image instead.

$ s2i build bin/Release/netcoreapp2.1/publish mywebapp registry.redhat.io/dotnet/dotnet-21-runtime-rhel7:2.1 -p always


In this article, you’ve learned how to create .NET Core application images using s2i. These images can be built directly from a git repository, local sources, or a pre-built application.

Last updated: March 24, 2023