-
Language:
English
-
Language:
English
Getting started with .NET on RHEL 8
Abstract
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 Core
.NET Core is a general-purpose development platform featuring automatic memory management and modern programming languages. Using .NET, you can build high-quality applications efficiently. .NET Core is available on Red Hat Enterprise Linux (RHEL) and OpenShift Container Platform through certified containers.
.NET Core 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 Core 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 Core 2.1 is supported on RHEL 7, RHEL 8, and OpenShift Container Platform versions 3.3 and later.
Chapter 2. Using .NET Core 2.1 on Red Hat Enterprise Linux 8
Learn how to install .NET Core 2.1 as well as create and publish .NET Core applications.
2.1. Installing .NET Core 2.1
.NET Core 2.1 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 Core 2.1 runtime with the latest 2.1 Software Development Kit (SDK). When a newer SDK becomes available for .NET Core 2.1, you can install it by running sudo yum update.
Prerequisites
Installed and registered RHEL 8 with attached subscriptions.
For more information, see Performing a standard RHEL installation.
Procedure
Install .NET Core 2.1 and all of its dependencies:
$ sudo yum install dotnet-sdk-2.1 -y
Verification steps
Verify the installation:
$ dotnet --info
The output returns the relevant information about the .NET Core installation and the environment.
2.2. Creating an application using .NET Core 2.1
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-appThe output returns:
The template "Console Application" was created successfully. Processing post-creation actions... Running 'dotnet restore' on my-app/my-app.csproj... Restoring packages for /home/username/my-app/my-app.csproj... Generating MSBuild file /home/username/my-app/obj/my-app.csproj.nuget.g.props. Generating MSBuild file /home/username/my-app/obj/my-app.csproj.nuget.g.targets. Restore completed in 224.85 ms for /home/username/my-app/my-app.csproj. Restore succeeded.
A simple
Hello Worldconsole application is created from a template. The application is stored in the specifiedmy-appdirectory.The directory includes the following files:
$ tree my-app my-app ├── my-app.csproj ├── obj │ ├── my-app.csproj.nuget.dgspec.json │ ├── my-app.csproj.nuget.g.props │ ├── my-app.csproj.nuget.g.targets │ ├── project.assets.json │ └── project.nuget.cache └── Program.cs 1 directory, 7 files
Verification steps
Run the project:
$ dotnet run --project my-appThe output returns:
Hello World!
2.3. Publishing applications using .NET Core 2.1
.NET Core 2.1 applications can be published to use a shared system-wide version of .NET Core or to include .NET Core.
The following methods exist for publishing .NET Core 2.1 applications:
- 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 Core, built by Red Hat, that includes a specific set of native dependencies.
- Self-contained deployment (SCD) - The application includes .NET. This method uses a runtime built by Microsoft.
Prerequisites
Existing .NET Core application.
For more information on how to create a .NET Core application, see Section 2.2, “Creating an application using .NET Core 2.1”.
2.3.1. Publishing .NET Core applications
Procedure
Publish the framework-dependent application:
$ dotnet publish my-app -f netcoreapp2.1 -c ReleaseReplace 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 netcoreapp2.1 -c Release -r rhel.8-x64 --self-contained false
2.3.2. Publishing ASP.NET applications
When using the Microsoft SDK, ASP.NET Core 2.1 web applications are published with a dependency on the ASP.NET Core shared framework. This is a set of packages that are expected to be available on the runtime system.
When publishing on RHEL, these packages are included with the application. To include the packages using the Microsoft SDK, the MicrosoftNETPlatformLibrary property must be set to Microsoft.NETCore.App in the project file as shown below.
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>netcoreapp2.1</TargetFramework>
<MicrosoftNETPlatformLibrary>Microsoft.NETCore.App</MicrosoftNETPlatformLibrary>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.App" Version="2.1" />
</ItemGroup>
</Project>This property can be set when publishing the application.
$ dotnet publish -f netcoreapp2.1 -c Release -r rhel.8-x64 --self-contained false /p:MicrosoftNETPlatformLibrary=Microsoft.NETCore.App
2.4. Running .NET Core 2.1 applications in containers
Use the ubi8/dotnet-21-runtime image to run a precompiled application inside a Linux container.
Prerequisites
Preconfigured containers.
The following example uses podman.
Procedure
Create a new MVC project in a directory called
mvc_runtime_example:$ dotnet new mvc --output mvc_runtime_example --no-restoreRestore and publish the project:
$ dotnet restore mvc_runtime_example -r rhel.8-x64 $ dotnet publish mvc_runtime_example -f netcoreapp2.1 -c Release -r rhel.8-x64 --self-contained false /p:MicrosoftNETPlatformLibrary=Microsoft.NETCore.App
Create the
Dockerfile:$ cat > Dockerfile <<EOF FROM registry.access.redhat.com/ubi8/dotnet-21-runtime ADD bin/Release/netcoreapp2.1/publish/ . CMD ["dotnet", "mvc_runtime_example.dll"] EOF
Build your image:
$ podman build -t dotnet-21-runtime-example .
Run your image:
$ podman run -d -p8080:8080 dotnet-21-runtime-example
Verification steps
View the application running in the container:
$ xdg-open http://127.0.0.1:8080
Chapter 3. Using .NET Core 2.1 on OpenShift Container Platform
You can install .NET Core image streams on Linux, Mac, or Windows operating system.
3.1. Installing .NET Core 2.1 image streams
.NET Core image streams definition can be defined globally in the openshift namespace or locally in your specific project.
Procedure
If you are a system administrator or otherwise have sufficient permissions, change to the
openshiftproject. Using theopenshiftproject allows you to globally update the image stream definitions.$ oc project openshift
If you do not have permissions to use the
openshiftproject, you can still update your project definitions starting with Step 2.List all available .NET Core image versions:
$ oc describe is dotnet -n openshift $ oc describe is dotnet
The output shows installed images or the message
Error from server (NotFound)if no images are installed.Import new image streams:
$ oc create -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/dotnet_imagestreams_rhel8.json
If image streams were already installed, use the
replacecommand to update the image stream definitions.$ oc replace -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/dotnet_imagestreams_rhel8.json
3.2. Deploying applications from source using oc
You can use OpenShift Client (oc) for application deployment.
The following example demonstrates how to deploy the example-app application using oc, which is in the app folder on the dotnetcore-2.1 branch of the redhat-developer/s2i-dotnetcore-ex GitHub repository:
Procedure
Create a new OpenShift project:
$ oc new-project sample-projectAdd the ASP.NET Core application:
$ oc new-app --name=example-app 'dotnet:2.1~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnetcore-2.1' --build-env DOTNET_STARTUP_PROJECT=appTrack the progress of the build:
$ oc logs -f bc/example-appView the deployed application once the build is finished:
$ oc logs -f dc/example-appThe application is now accessible within the project.
Optional: Make the project accessible externally:
$ oc expose svc/example-appObtain the shareable URL:
$ oc get routes
3.3. Deploying applications from binary artifacts using oc
You can use .NET Core Source-to-Image (S2I) builder image to build applications using binary artifacts that you provide.
Prerequisites
Published application.
For more information, see Section 2.3, “Publishing applications using .NET Core 2.1”.
Procedure
Create a new binary build:
$ oc new-build --name=my-web-app dotnet:2.1 --binary=trueStart the build and specify the path to the binary artifacts on your local machine:
$ oc start-build my-web-app --from-dir=bin/Release/netcoreapp2.1/publish
Create a new application:
$ oc new-app my-web-app
3.4. Environmental variables for .NET Core 2.1
The .NET Core images support several environment variables to control the build behavior of your .NET Core 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_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_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 | |
| [OBSOLETE: April 2019] - DOTNET_SDK_VERSION |
Selects the default sdk version when building. If there is a | Lowest sdk version available in the image |
3.5. Creating sample applications for .NET Core 2.1
Three sample applications are available:
- dotnet-example: This is the default model–view–controller (MVC) application.
-
dotnet-runtime-example: This shows how to build an MVC application using a chained build. The application is built in
ubi8/dotnet-21. The result is deployed inubi8/dotnet-21-runtime. Note that chained builds are not supported on OpenShift Online. - dotnet-pgsql-persistent: This is the Microsoft ASP.NET Core MusicStore sample application using a PostgreSQL backend.
To add the samples using the OpenShift Web Console, browse to your project and click Add to project. You can filter for dotnet. If the samples do not show up, you can add them to your installation by running the following commands:
$ oc create -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/templates/dotnet-example.json $ oc create -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/templates/dotnet-runtime-example.json $ oc create -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/templates/dotnet-pgsql-persistent.json
Chapter 4. Migration from previous versions of .NET Core
Microsoft provides instructions for migrating from most previous versions of .NET Core. When migrating, the following ASP.NET Core 2.0 property should no longer be specified. It should remain the default value for .NET Core 2.1. Make sure to remove this property from the project file and command line, if it is being specified there.
<PublishWithAspNetCoreTargetManifest>false</PublishWithAspNetCoreTargetManifest>
If you are using a version of .NET Core that is no longer supported or want to migrate to a newer .NET Core version to expand functionality, see the following articles:
- Migrate from .NET Core 2.0 to 2.1
- Migrate from ASP.NET Core 2.2 to 3.0
- Migrate from ASP.NET Core 2.1 to 2.2
- Migrate to ASP.NET Core
Migrate from project.json to .csproj format
- NOTE
- 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.
Chapter 5. Migration from .NET Framework to .NET Core 2.1
Review the following sections to find the instructions on how to migrate from the .NET Framework.
5.1. Migration considerations
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:
- 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 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'
Several APIs that are not supported in the default 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.
5.2. .NET Framework migration instructions
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.
Appendix A. Revision history
| Date | Version | Author | Changes |
|---|---|---|---|
| 08/21/2017 | 2.0 | Les Williams | Generally available |
| 08/30/2017 | 2.0 | Les Williams | Revised DOTNET_STARTUP_PROJECT and DOTNET_TEST_PROJECTS entries in Section 2.3 |
| 09/13/2017 | 2.0 | Les Williams | Revised Section 1.2 to include a note about how to permanently enable rh-dotnet20 |
| 02/14/2018 | 2.0 | Les Williams | Revised Section 2.2 to resolve BZ 1500230; added quoting for zsh and other shells |
| 02/28/2018 | 2.0.3 | Les Williams | Revised to include SDK 2.0 and 2.1 |
| 06/14/2018 | 2.1 | Les Williams | Generally available |
| 08/01/2018 | 2.1 | Toby Drake | Added Chapter 3 to provide migration instructions |
| 08/24/2018 | 2.1 | Toby Drake | Added steps to enable a user to get new image streams |
| 09/18/2018 | 2.1 | Toby Drake |
Revised Section 2.1 to include |
| 10/12/2018 | 2.1 | Toby Drake | Added DOTNET_SSL_DIRS and DOTNET_RM_SRC to ]. Added xref:deploying-applications-from-binary-artifacts_using-dotnet-on-openshift-container-platform[. |
| 11/08/2018 | 2.1 | Toby Drake |
Changed references from docker to podman. Changed registry server to |
| 11/27/2018 | 2.1 | Toby Drake | Added reference to support for RHEL 8. |
| 04/16/2019 | 2.2 | Les Williams | Revised environment variables section for DOTNET_INCREMENTAL and DOTNET_PACK variables |