Run .NET applications in containerized environments

You can build and run .NET applications in containers by using Podman, migrate existing applications to the latest .NET version, and configure environment variables to control the container build behavior.

Run .NET 10.0 applications in containers

To run .NET applications in an isolated environment, build container images directly from the .NET SDK and run them by using Podman.

Before you begin

  • You have installed .NET 10.0 SDK.
  • You have installed Podman.
  • You have network access to the container registry specified in the ContainerBaseImage attribute (registry.access.redhat.com).

About this task

You can use the ubi9/dotnet-100-aspnet image to run an ASP.NET Core application inside a Linux container.

For non-ASP.NET Core .NET applications, use the smaller ubi9/dotnet-100-runtime image.

Procedure

  1. Create a new ASP.NET Core MVC project in a directory named mvc_runtime_example:
    $ dotnet new mvc --output mvc_runtime_example
  2. Publish the project:
    $ dotnet publish mvc_runtime_example -f net10.0 /p:PublishProfile=DefaultContainer /p:ContainerBaseImage=registry.access.redhat.com/ubi9/dotnet-100-aspnet:latest
  3. Run your image:
    $ podman run --rm -p 8080:8080 mvc_runtime_example

Results

  1. View the application running in the container:
    $ xdg-open http://127.0.0.1:8080

Migrate from previous versions of .NET

To benefit from the latest performance improvements and long-term support, upgrade your existing applications to .NET 10.0. You can migrate from earlier .NET versions or port code from the .NET Framework to modernize your workloads.

Migration guidance for .NET

Microsoft provides detailed guidance for migrating between different versions of .NET and ASP.NET Core. If you are upgrading from an older .NET version, refer to the official Microsoft documentation for your specific upgrade path.

The following resources provide migration guidance for specific upgrade paths:

Note
If you are migrating from .NET Core 1.x to 2.0, the initial sections of the Migrate from ASP.NET Core 1.x to 2.0 article provide the relevant guidance.

Port from .NET Framework

When migrating an application from .NET Framework, refer to the official Microsoft documentation.

The following resources provide guidance for porting from .NET Framework:

Some technologies and APIs from .NET Framework are not available in .NET Core or .NET. If your application or library depends on these APIs, you must either find an alternative or remain on .NET Framework.

.NET Core and .NET do not support the following technologies:

  • Desktop applications, such as Windows Forms and Windows Presentation Foundation (WPF)
  • Windows Communication Foundation (WCF) servers (WCF clients are supported)
  • .NET remoting

Additionally, some .NET APIs are specific to Microsoft Windows environments and are not cross-platform. Examples of these Windows-specific APIs include:

  • Microsoft.Win32.Registry
  • System.AppDomains
  • System.Security.Principal.Windows
Important

Some APIs that are not supported by default in .NET are available in the Microsoft.Windows.Compatibility NuGet package.

Use this package with caution. Many of the APIs it provides, such as Microsoft.Win32.Registry, only work on Windows. Using these APIs makes your application incompatible with Red Hat Enterprise Linux.

Environment variables for Source-to-Image

The .NET images support several environment variables to control the build behavior of your .NET application. You can set these variables as part of the build configuration, or add them to the .s2i/environment file in the application source code repository.

Configuration variables

DOTNET_STARTUP_PROJECT
Description
Specifies the entry-point project to run. Provide a path to a project file (such as .csproj or .fsproj) or a directory that contains a single project file.
Default
None
DOTNET_ASSEMBLY_NAME
Description
Selects the assembly to run. Exclude the .dll extension. Set this value to match the AssemblyName specified in the project file.
Default
The name of the csproj file.
DOTNET_PUBLISH_READYTORUN
Description
Compiles the application in the ReadyToRun (R2R) format when set to true. This reduces startup time by pre-compiling assemblies and decreasing the Just-In-Time (JIT) compiler workload.
Default
false
DOTNET_RESTORE_SOURCES
Description
Specifies a space-separated list of NuGet package sources to use during the restore operation. This list overrides all sources in the NuGet.config file. Note: Do not use this variable with DOTNET_RESTORE_CONFIGFILE.
Default
None
DOTNET_RESTORE_CONFIGFILE
Description
Specifies a NuGet.Config file for restore operations. Note: Do not use this variable with DOTNET_RESTORE_SOURCES.
Default
None
DOTNET_TOOLS
Description
Specifies a list of .NET tools to install before the build process. To install a specific version, append @<version> to the package name.
Default
None
DOTNET_TEST_PROJECTS
Description
Specifies a list of test projects. Provide project files or folders that contain a single project file. The system invokes dotnet test for each item in the list.
Default
None
DOTNET_CONFIGURATION
Description
Sets the build configuration. Valid values are Release or Debug.
Default
Release
DOTNET_VERBOSITY
Description
Sets the verbosity level for dotnet build commands and prints environment variables at the start of the build. Use MSBuild verbosity values: q (quiet), m (minimal), n (normal), d (detailed), or diag (diagnostic).
Default
None
HTTP_PROXY / HTTPS_PROXY
Description
Configures the HTTP or HTTPS proxy for the application build and runtime environments.
Default
None
DOTNET_RM_SRC
Description
Excludes the source code from the final image when set to true.
Default
false
SSL_CERT_DIR
Description
Specifies a list of folders or files containing additional SSL certificates to trust. Every process that runs during or after the build trusts these certificates. Use absolute paths or paths relative to the source repository.
Default
None
ASPNETCORE_URLS
Description
Configures ASP.NET Core to use the port exposed by the image. The default is http://*:8080. Red Hat recommends that you do not change this value.
Default
http://*:8080
DOTNET_RESTORE_DISABLE_PARALLEL
Description
Disables parallel project restoration when set to true. Use this setting to prevent restore timeout errors in environments with low CPU limits.
Default
false
DOTNET_INCREMENTAL
Description
Retains NuGet packages for use in incremental builds when set to true.
Default
false
DOTNET_PACK
Description
Creates a tar.gz file at /opt/app-root/app.tar.gz that contains the published application when set to true.
Default
false