Skip to main content
Redhat Developers  Logo
  • Products

    Featured

    • Red Hat Enterprise Linux
      Red Hat Enterprise Linux Icon
    • Red Hat OpenShift AI
      Red Hat OpenShift AI
    • Red Hat Enterprise Linux AI
      Linux icon inside of a brain
    • Image mode for Red Hat Enterprise Linux
      RHEL image mode
    • Red Hat OpenShift
      Openshift icon
    • Red Hat Ansible Automation Platform
      Ansible icon
    • Red Hat Developer Hub
      Developer Hub
    • View All Red Hat Products
    • Linux

      • Red Hat Enterprise Linux
      • Image mode for Red Hat Enterprise Linux
      • Red Hat Universal Base Images (UBI)
    • Java runtimes & frameworks

      • JBoss Enterprise Application Platform
      • Red Hat build of OpenJDK
    • Kubernetes

      • Red Hat OpenShift
      • Microsoft Azure Red Hat OpenShift
      • Red Hat OpenShift Virtualization
      • Red Hat OpenShift Lightspeed
    • Integration & App Connectivity

      • Red Hat Build of Apache Camel
      • Red Hat Service Interconnect
      • Red Hat Connectivity Link
    • AI/ML

      • Red Hat OpenShift AI
      • Red Hat Enterprise Linux AI
    • Automation

      • Red Hat Ansible Automation Platform
      • Red Hat Ansible Lightspeed
    • Developer tools

      • Red Hat Trusted Software Supply Chain
      • Podman Desktop
      • Red Hat OpenShift Dev Spaces
    • Developer Sandbox

      Developer Sandbox
      Try Red Hat products and technologies without setup or configuration fees for 30 days with this shared Openshift and Kubernetes cluster.
    • Try at no cost
  • Technologies

    Featured

    • AI/ML
      AI/ML Icon
    • Linux
      Linux Icon
    • Kubernetes
      Cloud icon
    • Automation
      Automation Icon showing arrows moving in a circle around a gear
    • View All Technologies
    • Programming Languages & Frameworks

      • Java
      • Python
      • JavaScript
    • System Design & Architecture

      • Red Hat architecture and design patterns
      • Microservices
      • Event-Driven Architecture
      • Databases
    • Developer Productivity

      • Developer productivity
      • Developer Tools
      • GitOps
    • Secure Development & Architectures

      • Security
      • Secure coding
    • Platform Engineering

      • DevOps
      • DevSecOps
      • Ansible automation for applications and services
    • Automated Data Processing

      • AI/ML
      • Data Science
      • Apache Kafka on Kubernetes
      • View All Technologies
    • Start exploring in the Developer Sandbox for free

      sandbox graphic
      Try Red Hat's products and technologies without setup or configuration.
    • Try at no cost
  • Learn

    Featured

    • Kubernetes & Cloud Native
      Openshift icon
    • Linux
      Rhel icon
    • Automation
      Ansible cloud icon
    • Java
      Java icon
    • AI/ML
      AI/ML Icon
    • View All Learning Resources

    E-Books

    • GitOps Cookbook
    • Podman in Action
    • Kubernetes Operators
    • The Path to GitOps
    • View All E-books

    Cheat Sheets

    • Linux Commands
    • Bash Commands
    • Git
    • systemd Commands
    • View All Cheat Sheets

    Documentation

    • API Catalog
    • Product Documentation
    • Legacy Documentation
    • Red Hat Learning

      Learning image
      Boost your technical skills to expert-level with the help of interactive lessons offered by various Red Hat Learning programs.
    • Explore Red Hat Learning
  • Developer Sandbox

    Developer Sandbox

    • Access Red Hat’s products and technologies without setup or configuration, and start developing quicker than ever before with our new, no-cost sandbox environments.
    • Explore Developer Sandbox

    Featured Developer Sandbox activities

    • Get started with your Developer Sandbox
    • OpenShift virtualization and application modernization using the Developer Sandbox
    • Explore all Developer Sandbox activities

    Ready to start developing apps?

    • Try at no cost
  • Blog
  • Events
  • Videos

Containerize .NET applications without writing Dockerfiles

August 1, 2022
Tom Deseyn
Related topics:
.NETCI/CDContainersLinux
Related products:
Red Hat Enterprise Linux

Share:

    This article introduces dotnet build-image, a tool that containerizes .NET applications automatically. You can use build-image to create Dockerfiles and containerized images. You will also discover how to use the tool in a GitHub workflow to create an image from a .NET application and push it to a repository.

    Building an image or Dockerfile with dotnet build-image

    To run a .NET application in a container, you need a Dockerfile. At first, learning about Dockerfiles and writing them can be fun. But after a while, it becomes repetitive. Moreover, the files need to be kept in sync with the application. And if you have several applications, you need to keep updating their Dockerfiles to use the same style.

    The dotnet build-image is a global tool that writes the Dockerfile for you. The tool's features include:

    • It uses a multi-stage build: First, the application is published into one image, then the result is copied into a smaller runtime image.
    • The tool determines the .NET version an image should use from the .NET project (TargetFramework).
    • You can choose the image base's operating system, such as Ubuntu or Alpine.
    • It supports both Podman and Docker to build the image.
    • It caches NuGet packages across builds.
    • It uses the SDK version from global.json for publishing the application if the file is present.

    To get started, install the tool from NuGet:

    $ dotnet tool install -g dotnet-build-image

    Next, build an image from the default web template application:

    $ dotnet new web -o web
    $ cd web
    $ dotnet build-image -t mywebapp

    You will see the build in the terminal. Once the build is finished, run the image:

    $ podman run -p 8080:8080 mywebapp

    Open the web application in your browser at: http://localhost:8080.

    The tool has several options for you to explore by passing the argument: --help ​​​​.

    $ dotnet build-image --help
    Description:
      Build a container image from a .NET project.
    
    Usage:
      build-image [<PROJECT>] [options]
    
    Arguments:
      <PROJECT>  .NET project to build [default: .]
    
    Options:
      -b, --base <base>            	Flavor of the base image
      -t, --tag <tag>              	Name for the built image [default: dotnet-app]
      --push                       	After the build, push the image to the repository
      --as-dockerfile <as-dockerfile>  Generates a Dockerfile with the specified name
      --version                    	Show version information
      -?, -h, --help               	Show help and usage information

    We have already used the tag (-t) option.

    The --base option allows you to specify the base image. You can specify any base image that Microsoft publishes on the Microsoft Artifact Registry. When you specify ubi as the base, your application will use the .NET images from the Red Hat Ecosystem Catalog. Red Hat's UBI images are enterprise-grade images that can be freely distributed and deployed anywhere. To learn more, take a look at the UBI FAQ or read the e-book Red Hat Universal Base Images (UBI).

    As an alternative to specifying the options on the command line, add them to the csproj file:

      <PropertyGroup>
        <TargetFramework>net6.0</TargetFramework>
        <ImageTag>mywebapp</ImageTag>
        <ImageBase>ubi</ImageBase>
      </PropertyGroup>

    If you prefer to have a Dockerfile under version control, the tool can still be useful. Specify the --as-dockerfile Dockerfile argument to write out a Dockerfile instead of building an image. You can inspect the file and customize it.

    Using dotnet build-image in a GitHub workflow

    This section creates a GitHub repository and uses dotnet build-image in a GitHub workflow to set up continuous delivery (CI/CD) of a .NET application as a container image.

    As my image registry, I use my free account at Quay.io. Other registries such as Docker Hub work too.

    First, create a new repository and populate it with a .NET web app. I've named mine build-image-demo:

    $ git clone git@github.com:tmds/build-image-demo.git
    $ dotnet new web -o web --no-restore
    $ git add web
    $ git commit -m "Add web project"
    $ git push

    Add a global.json file that captures the SDK version you'd like contributors and CI to use:

    $ dotnet new globaljson --sdk-version 6.0.100 --roll-forward latestFeature
    $ git add global.json
    $ git commit -m "Use 6.0 SDK"
    $ git push

    Note that we've used the latestFeature argument. That permits the use of any 6.0.xxx SDK. Without that argument, the SDK is limited to the 6.0.1xx feature band.

    To use the Red Hat .NET images, add the ImageBase property in the web.csproj file. Add the line marked by a plus sign (+) in the PropertyGroup section:

       <PropertyGroup>
     	<TargetFramework>net6.0</TargetFramework>
     	<Nullable>enable</Nullable>
     	<ImplicitUsings>enable</ImplicitUsings>
    +	<ImageBase>ubi</ImageBase>
       </PropertyGroup>

    Include this change in your next commit:

    $ git add web/web.csproj

    Now, add the credentials for accessing the registry server to your GitHub project. Click the project's Settings link in the GitHub web interface and open the Environments tab. Then click New Environment and name it ImageRegistry. Add two secrets named REGISTRY_USER and REGISTRY_PASSWORD. These contain the credentials used to access the registry (Figure 1). After you add these values, verify that they work by using them with the podman login or docker login command.

    Add two secrets, REGISTRY_USER and REGISTRY_PASSWORD, in the GitHub project.
    Figure 1. Add two secrets, REGISTRY_USER and REGISTRY_PASSWORD, in the GitHub project.

     

    Now you're ready to add the workflow. Create a file at:  .github/workflows/deploy-image.yml and add the following content.

    name: Deploy Image
    
    on:
      push:
    	branches: [ "main" ]
    
    env:
      DOTNET_PROJECT: web
      REGISTRY: quay.io
      IMAGE_NAME: tmds/web
    
    jobs:
      deploy:
    
    	environment: ImageRegistry
    	runs-on: ubuntu-latest
    
    	steps:
    	- uses: actions/checkout@v3
    	- name: Install .NET
      	uses: actions/setup-dotnet@v2
    	- name: Install dotnet-build-image
      	run: dotnet tool install -g dotnet-build-image
    	- name: Log in to Image registry
      	run: echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login $REGISTRY -u "${{ secrets.REGISTRY_USER }}" --password-stdin
    	- name: Build and push image
      	run: dotnet build-image --push "$DOTNET_PROJECT" -t "$REGISTRY/$IMAGE_NAME"

    Update the REGISTRY and IMAGE_NAME properties under the env field to the right values for your image registry. If you're using Docker Hub, use docker.io as the REGISTRY.

    Let's take a look at the steps in the workflow:

    1. The first step (checkout) checks the source code.
    2. The next step (setup-dotnet) installs the .NET SDK using the version from global.json.
    3. A command runs which logs into the image registry.
    4. The last step runs the dotnet build-image tool to build the image and push it to the registry.

    When you've finished updating the file, push it to the repository:

    $ git add .github/workflows/deploy-image.yml
    $ git commit -m "Add deploy-image workflow."
    $ git push

    GitHub will trigger the workflow. You can follow progress under the Actions tab in the GitHub web interface.

    When you make changes to the web application and commit them to the main branch, it triggers the workflow that creates a new image and pushes it to the repository.

    $ podman run –rm -p 8080:8080 quay.io/tmds/web

    If you open the website at http://localhost:8080, the .NET application responds.

    Now when you make a change to the web application and commit it to the main branch, it triggers the workflow again and pushes a new image to the repository.

    Automating the Dockerfile creation

    In this article, you have learned how to use dotnet build-image to create a container image from a .NET application without writing a Dockerfile, and how to integrate build-image into a GitHub CI/CD workflow. To share feedback about this tool, please create a ticket in the GitHub repository.

    Last updated: August 14, 2023

    Related Posts

    • Dockerfiles now available for Red Hat Software Collections

    • Building .NET Core container images using S2I

    • .NET 5.0 now available for Red Hat Enterprise Linux and Red Hat OpenShift

    Recent Posts

    • GuideLLM: Evaluate LLM deployments for real-world inference

    • Unleashing multimodal magic with RamaLama

    • Integrate Red Hat AI Inference Server & LangChain in agentic workflows

    • Streamline multi-cloud operations with Ansible and ServiceNow

    • Automate dynamic application security testing with RapiDAST

    What’s up next?

    Getting GitOps e-book card

    Learn how to navigate the complex world of modern container-based software development and distribution with Getting GitOps: A Practical Platform with OpenShift, Argo CD, and Tekton.

    Get the e-book
    Red Hat Developers logo LinkedIn YouTube Twitter Facebook

    Products

    • Red Hat Enterprise Linux
    • Red Hat OpenShift
    • Red Hat Ansible Automation Platform

    Build

    • Developer Sandbox
    • Developer Tools
    • Interactive Tutorials
    • API Catalog

    Quicklinks

    • Learning Resources
    • E-books
    • Cheat Sheets
    • Blog
    • Events
    • Newsletter

    Communicate

    • About us
    • Contact sales
    • Find a partner
    • Report a website issue
    • Site Status Dashboard
    • Report a security problem

    RED HAT DEVELOPER

    Build here. Go anywhere.

    We serve the builders. The problem solvers who create careers with code.

    Join us if you’re a developer, software engineer, web designer, front-end designer, UX designer, computer scientist, architect, tester, product manager, project manager or team lead.

    Sign me up

    Red Hat legal and privacy links

    • About Red Hat
    • Jobs
    • Events
    • Locations
    • Contact Red Hat
    • Red Hat Blog
    • Inclusion at Red Hat
    • Cool Stuff Store
    • Red Hat Summit

    Red Hat legal and privacy links

    • Privacy statement
    • Terms of use
    • All policies and guidelines
    • Digital accessibility

    Report a website issue