Getting Started Guide
Abstract
- The ability to follow a microservices-based approach, where some components are built with .NET and others with Java, but all can run on a common, supported platform in Red Hat Enterprise Linux and OpenShift Container Platform.
- The capacity to more easily develop new .NET Core workloads on Microsoft Windows. Customers can deploy and run on either Red Hat Enterprise Linux or Windows Server.
- A heterogeneous data center, where the underlying infrastructure is capable of running .NET applications without having to rely solely on Windows Server.
Chapter 1. Using .NET Core 3.1 on Red Hat Enterprise Linux Copy linkLink copied to clipboard!
This Getting Started Guide describes how to install .NET Core 3.1 on Red Hat Enterprise Linux (RHEL). See Red Hat Enterprise Linux documentation for more information about RHEL 7.
1.1. Install and Register Red Hat Enterprise Linux Copy linkLink copied to clipboard!
Install RHEL 7 using one of the following images:
- Red Hat Enterprise Linux 7 Server
- Red Hat Enterprise Linux 7 Workstation
Red Hat Enterprise Linux for Scientific Computing
See the Red Hat Enterprise Linux Installation Guide for details on how to install RHEL.
See Red Hat Enterprise Linux Product Documentation page for available RHEL versions.
Use the following command to register the system.
sudo subscription-manager register
$ sudo subscription-manager registerCopy to Clipboard Copied! Toggle word wrap Toggle overflow You can also register the system by following the appropriate steps in Registering and Unregistering a System in the Red Hat Subscription Management document.
Display a list of all subscriptions that are available for your system and identify the pool ID for the subscription.
sudo subscription-manager list --available
$ sudo subscription-manager list --availableCopy to Clipboard Copied! Toggle word wrap Toggle overflow This command displays the subscription name, unique identifier, expiration date, and other details related to it. The pool ID is listed on a line beginning with Pool ID.
Attach the subscription that provides access to the
dotNET on RHELrepository. Use the pool ID you identified in the previous step.sudo subscription-manager attach --pool=<appropriate pool ID from the subscription>
$ sudo subscription-manager attach --pool=<appropriate pool ID from the subscription>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Enable the .NET Core channel for Red Hat Enterprise 7 Server, Red Hat Enterprise 7 Workstation, or HPC Compute Node with one of the following commands, respectively.
sudo subscription-manager repos --enable=rhel-7-server-dotnet-rpms sudo subscription-manager repos --enable=rhel-7-workstation-dotnet-rpms sudo subscription-manager repos --enable=rhel-7-hpc-node-dotnet-rpms
$ sudo subscription-manager repos --enable=rhel-7-server-dotnet-rpms $ sudo subscription-manager repos --enable=rhel-7-workstation-dotnet-rpms $ sudo subscription-manager repos --enable=rhel-7-hpc-node-dotnet-rpmsCopy to Clipboard Copied! Toggle word wrap Toggle overflow Verify the list of subscriptions attached to your system.
sudo subscription-manager list --consumed
$ sudo subscription-manager list --consumedCopy to Clipboard Copied! Toggle word wrap Toggle overflow Install the
scltool.sudo yum install scl-utils
$ sudo yum install scl-utilsCopy to Clipboard Copied! Toggle word wrap Toggle overflow
1.2. Install .NET Core Copy linkLink copied to clipboard!
Install .NET Core 3.1 and all of its dependencies.
sudo yum install rh-dotnet31 -y
$ sudo yum install rh-dotnet31 -yCopy to Clipboard Copied! Toggle word wrap Toggle overflow Enable the
rh-dotnet31Software Collection environment so you can rundotnetcommands in the bash shell.This procedure installs the .NET Core 3.1 runtime with the latest 3.1 SDK. When a newer SDK becomes available, it automatically installs as a package update.
scl enable rh-dotnet31 bash
$ scl enable rh-dotnet31 bashCopy to Clipboard Copied! Toggle word wrap Toggle overflow This command does not persist; it creates a new shell, and the
dotnetcommand is only available within that shell. If you log out, use another shell, or open up a new terminal, thedotnetcommand is no longer enabled.WarningRed Hat does not recommend permanently enabling
rh-dotnet31because it may affect other programs. For example,rh-dotnet31includes a version oflibcurlthat differs from the base RHEL version. This may lead to issues in programs that do not expect a different version oflibcurl. If you want to enablerh-dotnetpermanently, add the following line to your~/.bashrcfile.source scl_source enable rh-dotnet31Run the following command to verify the installation succeeded.
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.3. Create an Application Copy linkLink copied to clipboard!
Create a new Console application in a directory called
hello-world.Copy to Clipboard Copied! Toggle word wrap Toggle overflow Run the project.
cd hello-world dotnet run
$ cd hello-world $ dotnet run Hello World!Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.4. Publish Applications Copy linkLink copied to clipboard!
The .NET Core 3.1 applications can be published to use a shared system-wide version of .NET Core or to include .NET Core. These two deployment types are called framework-dependent deployment (FDD) and self-contained deployment (SCD), respectively.
For RHEL, we recommend publishing by FDD. This method ensures the application is using an up-to-date version of .NET Core, built by Red Hat, that includes a specific set of native dependencies. These native libraries are part of the rh-dotnet31 Software Collection. On the other hand, SCD uses a runtime built by Microsoft. Running applications outside the rh-dotnet31 Software Collection may cause issues due to the unavailability of native libraries.
Use the following command to publish a framework-dependent application.
dotnet publish -f netcoreapp3.1 -c Release
$ dotnet publish -f netcoreapp3.1 -c ReleaseCopy to Clipboard Copied! Toggle word wrap Toggle overflow Optional: If the application is only for RHEL, trim out the dependencies needed for other platforms with these commands.
dotnet restore -r rhel.7-x64 dotnet publish -f netcoreapp3.1 -c Release -r rhel.7-x64 --self-contained false
$ dotnet restore -r rhel.7-x64 $ dotnet publish -f netcoreapp3.1 -c Release -r rhel.7-x64 --self-contained falseCopy to Clipboard Copied! Toggle word wrap Toggle overflow Enable the Software Collection and pass the application name to run the application on a RHEL system.
scl enable rh-dotnet31 -- dotnet <app>.dll
$ scl enable rh-dotnet31 -- dotnet <app>.dllCopy to Clipboard Copied! Toggle word wrap Toggle overflow This command can be added to a script that is published with the application. Add the following script to your project and update the
APPvariable.Copy to Clipboard Copied! Toggle word wrap Toggle overflow To include the script when publishing, add this ItemGroup to the
csprojfile.<ItemGroup> <None Update="<scriptname>" Condition="'$(RuntimeIdentifier)' == 'rhel.7-x64' and '$(SelfContained)' == 'false'" CopyToPublishDirectory="PreserveNewest" /> </ItemGroup><ItemGroup> <None Update="<scriptname>" Condition="'$(RuntimeIdentifier)' == 'rhel.7-x64' and '$(SelfContained)' == 'false'" CopyToPublishDirectory="PreserveNewest" /> </ItemGroup>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.5. Run Applications on Linux Containers Copy linkLink copied to clipboard!
This section shows how to use the dotnet/dotnet-31-runtime-rhel7 image to run a precompiled application inside a Linux container.
Create a new mvc project in a directory named
mvc_runtime_example.dotnet new mvc -o mvc_runtime_example cd mvc_runtime_example
$ dotnet new mvc -o mvc_runtime_example $ cd mvc_runtime_exampleCopy to Clipboard Copied! Toggle word wrap Toggle overflow Publish the project.
dotnet publish -f netcoreapp3.1 -c Release
$ dotnet publish -f netcoreapp3.1 -c ReleaseCopy to Clipboard Copied! Toggle word wrap Toggle overflow Create the
Dockerfile.Copy to Clipboard Copied! Toggle word wrap Toggle overflow Build your image.
podman build -t dotnet-31-runtime-example .
$ podman build -t dotnet-31-runtime-example .Copy to Clipboard Copied! Toggle word wrap Toggle overflow NoteIf you get an error containing the message
unable to retrieve auth token: invalid username/password, you need to provide credentials for theregistry.redhat.ioserver. Use the command$ podman login registry.redhat.ioto log in. Your credentials are typically the same as those used for the Red Hat Customer Portal.Run your image.
podman run -d -p8080:8080 dotnet-31-runtime-example
$ podman run -d -p8080:8080 dotnet-31-runtime-exampleCopy to Clipboard Copied! Toggle word wrap Toggle overflow -
View the result in a browser:
http://127.0.0.1:8080.
Chapter 2. Using .NET Core 3.1 on Red Hat OpenShift Container Platform Copy linkLink copied to clipboard!
2.1. Installing Image Streams Copy linkLink copied to clipboard!
.NET Core image streams are installed using image stream definitions from s2i-dotnetcore with the OpenShift client oc. A script is available to facilitate removing/installing/updating the image streams.
.NET Core image streams can be defined in the global openshift namespace, or locally in a project namespace. To update the openshift namespace definitions, you need sufficient permissions.
Obtaining the RHEL 7 image streams requires authentication against the registry.redhat.io server using subscription credentials. These credentials are configured by adding a pull secret to the OpenShift namespace.
2.1.1. Install using oc Copy linkLink copied to clipboard!
- If no pull secret is present in the namespace, you must add one by following the instructions in Red Hat Container Registry Authentication.
Run the following commands to list the available .NET Core image streams.
oc describe is dotnet [-n <namespace>]
$ oc describe is dotnet [-n <namespace>]Copy to Clipboard Copied! Toggle word wrap Toggle overflow The output shows installed images or the message
Error from server (NotFound)if no images are installed.When .NET Core image streams are already installed, you can include newer versions by running:
oc replace -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/dotnet_imagestreams.json
$ oc replace -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/dotnet_imagestreams.jsonCopy to Clipboard Copied! Toggle word wrap Toggle overflow If no image streams for .NET Core are present, you can install them using:
oc create -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/dotnet_imagestreams.json
$ oc create -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/dotnet_imagestreams.jsonCopy to Clipboard Copied! Toggle word wrap Toggle overflow
2.1.2. Install using script Copy linkLink copied to clipboard!
The script can be used to install/remove/update .NET Core image streams.
2.1.3. Linux/macOS Copy linkLink copied to clipboard!
- Download the script from https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/install-imagestreams.sh
-
Login to the OpenShift cluster using the
oc logincommand. Install/update the imagestreams.
./install-imagestreams.sh --os rhel7 [--namespace <namespace>] [--user <subscription_user> --password <subscription_password>]
./install-imagestreams.sh --os rhel7 [--namespace <namespace>] [--user <subscription_user> --password <subscription_password>]Copy to Clipboard Copied! Toggle word wrap Toggle overflow
The pull secret can be added by providing the --user and --password arguments. If a pull secret is already present, these arguments are ignored.
You can run ./install-imagestreams.sh --help for more information on using this script.
2.1.4. Windows Copy linkLink copied to clipboard!
- Download the script from https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/install-imagestreams.ps1
-
Login to the OpenShift cluster using the
oc logincommand. Install/update the imagestreams.
./install-imagestreams.sh --OS rhel7 [--Namespace <namespace>] [-User <subscription_user> -Password <subscription_password>]
./install-imagestreams.sh --OS rhel7 [--Namespace <namespace>] [-User <subscription_user> -Password <subscription_password>]Copy to Clipboard Copied! Toggle word wrap Toggle overflow
The PowerShell ExecutionPolicy may prohibit executing this script. To relax the policy, you can run Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force.
The pull secret can be added by providing the -User and -Password arguments. If a pull secret is already present, these arguments are ignored.
You can run Get-Help .\install-imagestreams.ps1 for more information on using this script.
2.2. Deploying Applications from Source Copy linkLink copied to clipboard!
Run the following commands to deploy the ASP.NET Core application, which is in the
appfolder on thedotnetcore-3.1branch of theredhat-developer/s2i-dotnetcore-exGitHub repository.oc new-app --name=exampleapp 'dotnet:3.1~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnetcore-3.1' --build-env DOTNET_STARTUP_PROJECT=app
$ oc new-app --name=exampleapp 'dotnet:3.1~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnetcore-3.1' --build-env DOTNET_STARTUP_PROJECT=appCopy to Clipboard Copied! Toggle word wrap Toggle overflow Use the
oc logscommand to track progress of the build.oc logs -f bc/exampleapp
$ oc logs -f bc/exampleappCopy to Clipboard Copied! Toggle word wrap Toggle overflow View the deployed application once the build is finished.
oc logs -f dc/exampleapp
$ oc logs -f dc/exampleappCopy to Clipboard Copied! Toggle word wrap Toggle overflow At this point, the application is accessible within the project. To make it accessible externally, use the
oc exposecommand. You can then useoc get routesto find the URL.oc expose svc/exampleapp oc get routes
$ oc expose svc/exampleapp $ oc get routesCopy to Clipboard Copied! Toggle word wrap Toggle overflow
2.3. Deploying Applications from Binary Artifacts Copy linkLink copied to clipboard!
The .NET Core S2I builder image can be used to build an application using binary artifacts that you provide.
Publish your application as described in Publish Applications. For example, the following commands create a new web application and publish it.
dotnet new web -o webapp cd webapp dotnet publish -c Release
$ dotnet new web -o webapp $ cd webapp $ dotnet publish -c ReleaseCopy to Clipboard Copied! Toggle word wrap Toggle overflow Create a new binary build using the
oc new-buildcommand.oc new-build --name=mywebapp dotnet:3.1 --binary=true
$ oc new-build --name=mywebapp dotnet:3.1 --binary=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Start a build using the
oc start-buildcommand, specifying the path to the binary artifacts on your local machine.oc start-build mywebapp --from-dir=bin/Release/netcoreapp3.1/publish
$ oc start-build mywebapp --from-dir=bin/Release/netcoreapp3.1/publishCopy to Clipboard Copied! Toggle word wrap Toggle overflow Create a new application using the
oc new-appcommand.oc new-app mywebapp
$ oc new-app mywebappCopy to Clipboard Copied! Toggle word wrap Toggle overflow
2.4. Using a Jenkins Slave Copy linkLink copied to clipboard!
The OpenShift Container Platform Jenkins image provides auto-discovery of the .NET Core 3.1 slave image (dotnet-31). For auto-discovery to work, you need to add a Jenkins slave ConfigMap yaml file to the project.
Change to the project where Jenkins is (or will be) deployed.
oc project <projectname>
$ oc project <projectname>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Create a
dotnet-jenkins-slave.yamlfile. The value used for the <serviceAccount> element is the account used by the Jenkins slave. If no value is specified, thedefaultservice account is used.Copy to Clipboard Copied! Toggle word wrap Toggle overflow Import the configuration into the project.
oc create -f dotnet-jenkins-slave.yaml
$ oc create -f dotnet-jenkins-slave.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow The slave image can now be used.
Example: The following example shows a Jenkins pipeline added to OpenShift Container Platform. Note that when a Jenkins pipeline is added and no Jenkins master is running, OpenShift automatically deploys a master. See OpenShift Container Platform and Jenkins for additional information about deploying and configuring a Jenkins server instance.
In the example steps, the BuildConfig yaml file includes a simple Jenkins pipeline configured using the dotnet-31 Jenkins slave. There are three stages in the example BuildConfig yaml file:
-
First, the sources are checked out.
-
Second, the application is published.
- Third, the image is assembled using a binary build. See Deploying Applications from Binary Artifacts for additional information about binary builds.
Complete the steps below to configure the example Jenkins master-slave pipeline.
Create the
buildconfig.yamlfile.Copy to Clipboard Copied! Toggle word wrap Toggle overflow Import the
BuildConfigfile to OpenShift.oc create -f buildconfig.yaml
$ oc create -f buildconfig.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow -
Launch the OpenShift console. Go to Builds > Pipelines. The
dotnetapp-buildpipeline is available. Click Start Pipeline. It may take a while for the build to start because the Jenkins image(s) need to be downloaded first.
During the build you can watch the different pipeline stages complete in the OpenShift console. You can also click View Log to see the pipeline stages complete in Jenkins.
-
When the Jenkins pipeline build completes, go to Builds > Images. The
dotnetappimage is built and available.
2.5. Environment Variables Copy linkLink copied to clipboard!
The .NET Core images support a number of environment variables to control the build behavior of your .NET Core application. These variables can be set as part of the build configuration, or they can be added to an .s2i/environment file in the application source code repository.
| Variable Name | Description | Default |
|---|---|---|
| DOTNET_STARTUP_PROJECT |
Selects project to run. This must be a project file (for example, |
|
| DOTNET_ASSEMBLY_NAME |
Selects the assembly to run. This must not include the .dll extension. Set this to the output assembly name specified in |
The name of the |
| DOTNET_PUBLISH_READRYTORUN |
When set to |
|
| DOTNET_RESTORE_SOURCES |
Specifies the space-separated list of NuGet package sources used during the restore operation. This overrides all of the sources specified in the | |
| DOTNET_RESTORE_CONFIGFILE |
Specifies a | |
| DOTNET_TOOLS |
Specifies a list of .NET tools to install before building the app. It is possible to install a specific version by post pending the package name with | |
| DOTNET_NPM_TOOLS | Specifies a list of NPM packages to install before building the application. | |
| DOTNET_TEST_PROJECTS |
Specifies the list of test projects to test. This must be project files or folders containing a single project file. | |
| DOTNET_CONFIGURATION |
Runs the application in Debug or Release mode. This value should be either |
|
| DOTNET_VERBOSITY |
Specifies the verbosity of the | |
| HTTP_PROXY, HTTPS_PROXY | Configures the HTTP/HTTPS proxy used when building and running the application. | |
| DOTNET_RM_SRC |
When set to | |
| DOTNET_SSL_DIRS |
Used to specify a list of folders/files with additional SSL certificates to trust. The certificates are trusted by each process that runs during the build and all processes that run in the image after the build (including the application that was built). The items can be absolute paths (starting with | |
| NPM_MIRROR | Uses a custom NPM registry mirror to download packages during the build process. | |
| ASPNETCORE_URLS |
This variable is set to | |
| DOTNET_RESTORE_DISABLE_PARALLEL | When set to true, disables restoring multiple projects in parallel. This reduces restore timeout errors when the build container is running with low CPU limits. |
|
| DOTNET_INCREMENTAL | When set to true, the NuGet packages will be kept so they can be re-used for an incremental build. |
|
| DOTNET_PACK |
When set to true, creates a |
2.6. Sample Applications Copy linkLink copied to clipboard!
Two sample applications are available for use with the .NET Core s2i builder.
2.6.1. s2i-dotnetcore-ex Copy linkLink copied to clipboard!
s2i-dotnetcore-ex is the default .NET Core MVC template application.
This application is used as the example application by the .NET Core s2i image and can be created directly from the OpenShift UI using the Try Example link.
The application can also be created with the OpenShift client oc as follows:
For more information about this application, see https://github.com/redhat-developer/s2i-dotnetcore-ex/tree/dotnetcore-3.1.
2.6.2. s2i-dotnetcore-persistent-ex Copy linkLink copied to clipboard!
s2i-dotnetcore-persistent-ex is the a simple CRUD .NET Core web application that stores data in a PostgreSQL database.
The application can be created using the OpenShift client oc as follows:
For more information about this application, see https://github.com/redhat-developer/s2i-dotnetcore-persistent-ex/tree/dotnetcore-3.1.
Chapter 3. Migrating to .NET Core 3.1 Copy linkLink copied to clipboard!
This chapter provides migration information for .NET Core 3.1.
3.1. Migrating from previous versions of .NET Core Copy linkLink copied to clipboard!
See the following Microsoft articles to migrate from previous versions of .NET Core to newer versions of .NET Core.
3.2. Migrating from .NET Framework to .NET Core 3.1 Copy linkLink copied to clipboard!
Review the following information to migrate from the .NET Framework.
3.2.1. Migration Considerations Copy linkLink copied to clipboard!
Several technologies and APIs present in the .NET Framework are not available in .NET Core. If your application or library requires these APIs, consider finding alternatives or continue using the .NET Framework. .NET Core does not support the following technologies and APIs:
- Windows Communication Foundation (WCF) servers (WCF clients are supported)
- .NET remoting
Additionally, a number of .NET APIs can only be used in Microsoft Windows environments. The following list shows a few examples of these Windows-specific APIs:
- Microsoft.Win32.Registry
- System.AppDomains
- System.Security.Principal.Windows
Consider using the .NET Portability Analyzer to identify API gaps and potential replacements. For example, enter the following command to find out how much of the API used by your .NET Framework 4.6 application is supported by .NET Core 2.1.
dotnet /path/to/ApiPort.dll analyze -f . -r html --target '.NET Framework,Version=4.6' --target '.NET Core,Version=2.1'
$ dotnet /path/to/ApiPort.dll analyze -f . -r html --target '.NET Framework,Version=4.6' --target '.NET Core,Version=2.1'
Several APIs that are not supported in the out-of-the-box version of .NET Core may be available from the Microsoft.Windows.Compatibility nuget package. Be careful when using this nuget package. Some of the APIs provided (such as Microsoft.Win32.Registry) only work on Windows, making your application incompatible with Red Hat Enterprise Linux.
3.2.2. .NET Framework Migration Articles Copy linkLink copied to clipboard!
Refer to the following Microsoft articles when migrating from .NET Framework.
- For general guidelines, see Porting to .NET Core from .NET Framework.
- For porting libraries, see Porting to .NET Core - Libraries.
- For migrating to ASP.NET Core, see Migrating to ASP.NET Core.