此内容没有您所选择的语言版本。
Getting started with .NET on RHEL 8
Installing and running .NET 5.0 on RHEL 8
Abstract
Making open source more inclusive 复制链接链接已复制到粘贴板!
Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.
Providing feedback on Red Hat documentation 复制链接链接已复制到粘贴板!
We appreciate your input on our documentation. Please let us know how we could make it better. To do so:
For simple comments on specific passages:
- Make sure you are viewing the documentation in the Multi-page HTML format. In addition, ensure you see the Feedback button in the upper right corner of the document.
- Use your mouse cursor to highlight the part of text that you want to comment on.
- Click the Add Feedback pop-up that appears below the highlighted text.
- Follow the displayed instructions.
For submitting more complex feedback, create a Bugzilla ticket:
- Go to the Bugzilla website.
- As the Component, use Documentation.
- Fill in the Description field with your suggestion for improvement. Include a link to the relevant part(s) of documentation.
- Click Submit Bug.
Chapter 1. Introducing .NET 5.0 复制链接链接已复制到粘贴板!
.NET is a general-purpose development platform featuring automatic memory management and modern programming languages. Using .NET, you can build high-quality applications efficiently. .NET is available on Red Hat Enterprise Linux (RHEL) and OpenShift Container Platform through certified containers.
.NET offers the following features:
- 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 on RHEL and OpenShift Container Platform.
- The capacity to more easily develop new .NET workloads on Microsoft Windows. You can deploy and run your applications on either RHEL 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.
.NET 5.0 is supported on RHEL 7, RHEL 8, and OpenShift Container Platform versions 3.11 and later.
Chapter 2. Installing .NET 5.0 复制链接链接已复制到粘贴板!
.NET 5.0 is included in the AppStream repositories for RHEL 8. The AppStream repositories are enabled by default on RHEL 8 systems.
You can install the .NET 5.0 runtime with the latest 5.0 Software Development Kit (SDK). When a newer SDK becomes available for .NET 5.0, you can install it by running sudo yum install.
Prerequisites
Installed and registered RHEL 8 with attached subscriptions.
For more information, see Performing a standard RHEL installation.
Procedure
Install .NET 5.0 and all of its dependencies:
sudo yum install dotnet-sdk-5.0 -y
$ sudo yum install dotnet-sdk-5.0 -yCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Verification steps
Verify the installation:
dotnet --info
$ dotnet --infoCopy to Clipboard Copied! Toggle word wrap Toggle overflow The output returns the relevant information about the .NET installation and the environment.
Chapter 3. Creating an application using .NET 5.0 复制链接链接已复制到粘贴板!
Learn how to create a C# hello-world application.
Procedure
Create a new Console application in a directory called
my-app:dotnet new console --output my-app
$ dotnet new console --output my-appCopy to Clipboard Copied! Toggle word wrap Toggle overflow The output returns:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow A simple
Hello Worldconsole application is created from a template. The application is stored in the specifiedmy-appdirectory.
Verification steps
Run the project:
dotnet run --project my-app
$ dotnet run --project my-appCopy to Clipboard Copied! Toggle word wrap Toggle overflow The output returns:
Hello World!
Hello World!Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Chapter 4. Publishing applications with .NET 5.0 复制链接链接已复制到粘贴板!
.NET 5.0 applications can be published to use a shared system-wide version of .NET or to include .NET.
The following methods exist for publishing .NET 5.0 applications:
- Single-file application - The application is self-contained and can be deployed as a single executable with all dependent files contained in a single binary.
- Framework-dependent deployment (FDD) - The application uses a shared system-wide version of .NET.
When publishing an application for RHEL, Red Hat recommends using FDD, because it ensures that the application is using an up-to-date version of .NET, built by Red Hat, that uses a set of native dependencies.
- Self-contained deployment (SCD) - The application includes .NET. This method uses a runtime built by Microsoft.
Prerequisites
Existing .NET application.
For more information on how to create a .NET application, see Creating an application using .NET.
4.1. Publishing .NET applications 复制链接链接已复制到粘贴板!
The following procedure outlines how to publish a framework-dependent application.
Procedure
Publish the framework-dependent application:
dotnet publish my-app -f net5.0 -c Release
$ dotnet publish my-app -f net5.0 -c ReleaseCopy to Clipboard Copied! Toggle word wrap Toggle overflow Replace my-app with the name of the application you want to publish.
Optional: If the application is for RHEL only, trim out the dependencies needed for other platforms:
dotnet restore my-app -r rhel.8-x64 dotnet publish my-app -f net5.0 -c Release -r rhel.8-x64 --self-contained false
$ dotnet restore my-app -r rhel.8-x64 $ dotnet publish my-app -f net5.0 -c Release -r rhel.8-x64 --self-contained falseCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Chapter 5. Running .NET 5.0 applications in containers 复制链接链接已复制到粘贴板!
Use the ubi8/dotnet-50-runtime image to run a precompiled application inside a Linux container.
Prerequisites
Preconfigured containers.
The following example uses podman.
Procedure
Optional: If you are in another project’s directory and do not wish to create a nested project, return to the parent directory of the project:
cd ..
# cd ..Copy to Clipboard Copied! Toggle word wrap Toggle overflow Create a new MVC project in a directory called
mvc_runtime_example:dotnet new mvc --output mvc_runtime_example
$ dotnet new mvc --output mvc_runtime_exampleCopy to Clipboard Copied! Toggle word wrap Toggle overflow Publish the project:
dotnet publish mvc_runtime_example -f net5.0 -c Release
$ dotnet publish mvc_runtime_example -f net5.0 -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-50-runtime-example .
$ podman build -t dotnet-50-runtime-example .Copy to Clipboard Copied! Toggle word wrap Toggle overflow Run your image:
podman run -d -p8080:8080 dotnet-50-runtime-example
$ podman run -d -p8080:8080 dotnet-50-runtime-exampleCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Verification steps
View the application running in the container:
xdg-open http://127.0.0.1:8080
$ xdg-open http://127.0.0.1:8080Copy to Clipboard Copied! Toggle word wrap Toggle overflow
6.1. Overview 复制链接链接已复制到粘贴板!
NET images are added to OpenShift by importing imagestream definitions from s2i-dotnetcore.
The imagestream definitions includes the dotnet imagestream which contains sdk images for different supported versions of .NET. .NET Life Cycle provides an up-to-date overview of supported versions.
| Version | Tag | Alias |
|---|---|---|
| .NET Core 3.1 | dotnet:3.1-el7 | dotnet:3.1 |
| dotnet:3.1-ubi8 | ||
| .NET 5 | dotnet:5.0-ubi8 | dotnet:5.0 |
| .NET 6 | dotnet:6.0-ubi8 | dotnet:6.0 |
The sdk images have corresponding runtime images which are defined under the dotnet-runtime imagestream.
The container images work across different versions of Red Hat Enterprise Linux and OpenShift.
The RHEL7-based (suffix -el7) are hosted on the registry.redhat.io image repository. Authentication is required to pull these images. These credentials are configured by adding a pull secret to the OpenShift namespace.
The UBI-8 based images (suffix -ubi8) are hosted on the registry.access.redhat.com and do not require authentication.
6.2. Installing .NET image streams 复制链接链接已复制到粘贴板!
To install .NET image streams, use image stream definitions from s2i-dotnetcore with the OpenShift Client (oc) binary. Image streams can be installed from Linux, Mac, and Windows. A script enables you to install, update or remove the image streams.
You can define .NET image streams in the global openshift namespace or locally in a project namespace. Sufficient permissions are required to update the openshift namespace definitions.
6.2.1. Installing image streams using OpenShift Client 复制链接链接已复制到粘贴板!
You can use OpenShift Client (oc) to install .NET image streams.
Prerequisites
- An existing pull secret must be present in the namespace. If no pull secret is present in the namespace. Add one by following the instructions in the Red Hat Container Registry Authentication guide.
Procedure
List the available .NET image streams:
oc describe is dotnet
$ oc describe is dotnetCopy to Clipboard Copied! Toggle word wrap Toggle overflow The output shows installed images. If no images are installed, the
Error from server (NotFound)message is displayed.If the
Error from server (NotFound)message is displayed:Install the .NET image streams:
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
If the
Error from server (NotFound)message is not displayed:You can include newer versions of existing .NET image streams:
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
6.2.2. Installing image streams on Linux and macOS 复制链接链接已复制到粘贴板!
You can use this script to install, upgrade, or remove the image streams on Linux and macOS.
Procedure
Download the script.
On Linux use:
wget https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/install-imagestreams.sh
$ wget https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/install-imagestreams.shCopy to Clipboard Copied! Toggle word wrap Toggle overflow On Mac use:
curl https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/install-imagestreams.sh -o install-imagestreams.sh
$ curl https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/install-imagestreams.sh -o install-imagestreams.shCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Make the script executable:
chmod +x install-imagestreams.sh
$ chmod +x install-imagestreams.shCopy to Clipboard Copied! Toggle word wrap Toggle overflow Log in to the OpenShift cluster:
oc login
$ oc loginCopy to Clipboard Copied! Toggle word wrap Toggle overflow Install image streams and add a pull secret for authentication against the
registry.redhat.io:./install-imagestreams.sh --os rhel [--user subscription_username --password subscription_password]
./install-imagestreams.sh --os rhel [--user subscription_username --password subscription_password]Copy to Clipboard Copied! Toggle word wrap Toggle overflow Replace subscription_username with the name of the user, and replace subscription_password with the user’s password. The credentials may be omitted if you do not plan to use the RHEL7-based images.
If the pull secret is already present, the
--userand--passwordarguments are ignored.
Additional information
-
./install-imagestreams.sh --help
6.2.3. Installing image streams on Windows 复制链接链接已复制到粘贴板!
You can use this script to install, upgrade, or remove the image streams on Windows.
Procedure
Download the script.
Invoke-WebRequest https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/install-imagestreams.ps1 -UseBasicParsing -OutFile install-imagestreams.ps1
Invoke-WebRequest https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/install-imagestreams.ps1 -UseBasicParsing -OutFile install-imagestreams.ps1Copy to Clipboard Copied! Toggle word wrap Toggle overflow Log in to the OpenShift cluster:
oc login
$ oc loginCopy to Clipboard Copied! Toggle word wrap Toggle overflow Install image streams and add a pull secret for authentication against the
registry.redhat.io:.\install-imagestreams.ps1 --OS rhel [-User subscription_username -Password subscription_password]
.\install-imagestreams.ps1 --OS rhel [-User subscription_username -Password subscription_password]Copy to Clipboard Copied! Toggle word wrap Toggle overflow Replace subscription_username with the name of the user, and replace subscription_password with the user’s password. The credentials may be omitted if you do not plan to use the RHEL7-based images.
If the pull secret is already present, the
-Userand-Passwordarguments are ignored.
The PowerShell ExecutionPolicy may prohibit executing this script. To relax the policy, run Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force.
Additional information
-
Get-Help .\install-imagestreams.ps1
6.3. Deploying applications from source using oc 复制链接链接已复制到粘贴板!
The following example demonstrates how to deploy the example-app application using oc, which is in the app folder on the dotnet-5.0 branch of the redhat-developer/s2i-dotnetcore-ex GitHub repository:
Procedure
Create a new OpenShift project:
oc new-project sample-project
$ oc new-project sample-projectCopy to Clipboard Copied! Toggle word wrap Toggle overflow Add the ASP.NET Core application:
oc new-app --name=example-app 'dotnet:5.0-ubi8~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnet-5.0' --build-env DOTNET_STARTUP_PROJECT=app
$ oc new-app --name=example-app 'dotnet:5.0-ubi8~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnet-5.0' --build-env DOTNET_STARTUP_PROJECT=appCopy to Clipboard Copied! Toggle word wrap Toggle overflow Track the progress of the build:
oc logs -f bc/example-app
$ oc logs -f bc/example-appCopy to Clipboard Copied! Toggle word wrap Toggle overflow View the deployed application once the build is finished:
oc logs -f dc/example-app
$ oc logs -f dc/example-appCopy to Clipboard Copied! Toggle word wrap Toggle overflow The application is now accessible within the project.
Optional: Make the project accessible externally:
oc expose svc/example-app
$ oc expose svc/example-appCopy to Clipboard Copied! Toggle word wrap Toggle overflow Obtain the shareable URL:
oc get routes
$ oc get routesCopy to Clipboard Copied! Toggle word wrap Toggle overflow
You can use .NET Source-to-Image (S2I) builder image to build applications using binary artifacts that you provide.
Prerequisites
Published application.
For more information, see Publishing applications with .NET 6.0.
Procedure
Create a new binary build:
oc new-build --name=my-web-app dotnet:5.0-ubi8 --binary=true
$ oc new-build --name=my-web-app dotnet:5.0-ubi8 --binary=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Start the build and specify the path to the binary artifacts on your local machine:
oc start-build my-web-app --from-dir=bin/Release/net5.0/publish
$ oc start-build my-web-app --from-dir=bin/Release/net5.0/publishCopy to Clipboard Copied! Toggle word wrap Toggle overflow Create a new application:
oc new-app my-web-app
$ oc new-app my-web-appCopy to Clipboard Copied! Toggle word wrap Toggle overflow
6.5. Environment variables for .NET 5.0 复制链接链接已复制到粘贴板!
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.
| Variable Name | Description | Default |
|---|---|---|
| DOTNET_STARTUP_PROJECT |
Selects the project to run. This must be a project file (for example, |
|
| DOTNET_ASSEMBLY_NAME |
Selects the assembly to run. This must not include the |
The name of the |
| DOTNET_PUBLISH_READYTORUN |
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 or HTTPS proxy used when building and running the application, respectively. | |
| DOTNET_RM_SRC |
When set to | |
| DOTNET_SSL_DIRS |
Specifies a list of folders or 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 |
|
| DOTNET_INCREMENTAL |
When set to |
|
| DOTNET_PACK |
When set to |
6.6. Creating the MVC sample application 复制链接链接已复制到粘贴板!
s2i-dotnetcore-ex is the default Model, View, Controller (MVC) template application for .NET.
This application is used as the example application by the .NET 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 binary (oc).
Procedure
To create the sample application using oc:
Add the .NET application:
oc new-app dotnet:5.0-ubi8~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnet-5.0 --context-dir=app
$ oc new-app dotnet:5.0-ubi8~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnet-5.0 --context-dir=appCopy to Clipboard Copied! Toggle word wrap Toggle overflow Make the application accessible externally:
oc expose service s2i-dotnetcore-ex
$ oc expose service s2i-dotnetcore-exCopy to Clipboard Copied! Toggle word wrap Toggle overflow Obtain the sharable URL:
oc get route s2i-dotnetcore-ex
$ oc get route s2i-dotnetcore-exCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Additional resources
6.7. Creating the CRUD sample application 复制链接链接已复制到粘贴板!
s2i-dotnetcore-persistent-ex is a simple Create, Read, Update, Delete (CRUD) .NET web application that stores data in a PostgreSQL database.
Procedure
To create the sample application using oc:
Add the database:
oc new-app postgresql-ephemeral
$ oc new-app postgresql-ephemeralCopy to Clipboard Copied! Toggle word wrap Toggle overflow Add the .NET application:
oc new-app dotnet:5.0-ubi8~https://github.com/redhat-developer/s2i-dotnetcore-persistent-ex#dotnet-5.0 --context-dir app
$ oc new-app dotnet:5.0-ubi8~https://github.com/redhat-developer/s2i-dotnetcore-persistent-ex#dotnet-5.0 --context-dir appCopy to Clipboard Copied! Toggle word wrap Toggle overflow Add environment variables from the
postgresqlsecret and database service name environment variable:oc set env dc/s2i-dotnetcore-persistent-ex --from=secret/postgresql -e database-service=postgresql
$ oc set env dc/s2i-dotnetcore-persistent-ex --from=secret/postgresql -e database-service=postgresqlCopy to Clipboard Copied! Toggle word wrap Toggle overflow Make the application accessible externally:
oc expose service s2i-dotnetcore-persistent-ex
$ oc expose service s2i-dotnetcore-persistent-exCopy to Clipboard Copied! Toggle word wrap Toggle overflow Obtain the sharable URL:
oc get route s2i-dotnetcore-persistent-ex
$ oc get route s2i-dotnetcore-persistent-exCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Additional resources
Chapter 7. Migration from previous versions of .NET 复制链接链接已复制到粘贴板!
7.1. Migration from previous versions of .NET 复制链接链接已复制到粘贴板!
Microsoft provides instructions for migrating from most previous versions of .NET Core.
If you are using a version of .NET that is no longer supported or want to migrate to a newer .NET version to expand functionality, see the following articles:
- Migrate from ASP.NET Core 5.0 to 6.0
- Migrate from ASP.NET Core 3.1 to 5.0
- Migrate from ASP.NET Core 3.0 to 3.1
- Migrate from ASP.NET Core 2.2 to 3.0
- Migrate from ASP.NET Core 2.1 to 2.2
- Migrate from .NET Core 2.0 to 2.1
- Migrate from ASP.NET to ASP.NET Core
- Migrating .NET Core projects from project.json
- Migrate from project.json to .csproj format
If migrating from .NET Core 1.x to 2.0, see the first few related sections in Migrate from ASP.NET Core 1.x to 2.0. These sections provide guidance that is appropriate for a .NET Core 1.x to 2.0 migration path.
7.2. Porting from .NET Framework 复制链接链接已复制到粘贴板!
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.
Several technologies and APIs present in the .NET Framework are not available in .NET Core and .NET. If your application or library requires these APIs, consider finding alternatives or continue using the .NET Framework. .NET Core and .NET do not support the following technologies and APIs:
- Desktop applications, for example, Windows Forms and Windows Presentation Foundation (WPF)
- Windows Communication Foundation (WCF) servers (WCF clients are supported)
- .NET remoting
Additionally, several .NET APIs can only be used in Microsoft Windows environments. The following list shows examples of these Windows-specific APIs:
-
Microsoft.Win32.Registry -
System.AppDomains -
System.Drawing -
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 application is supported by .NET 5.0:
dotnet /path/to/ApiPort.dll analyze -f . -r html --target '.NET Framework,Version=<dotnet-framework-version>' --target '.NET Core,Version=<dotnet-version>'
$ dotnet /path/to/ApiPort.dll analyze -f . -r html --target '.NET Framework,Version=<dotnet-framework-version>' --target '.NET Core,Version=<dotnet-version>'
Replace <dotnet-framework-version> with the .NET Framework version you are currently using. For example, 4.6. Replace <dotnet-version> with the version of .NET Core you plan to migrate to. For example, 3.1.
Several APIs that are not supported in the default version of .NET 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.