In this article, you'll learn how to deploy a .NET Worker Service to Azure. With your Worker running as an Azure Container Instance (ACI) from the Azure Container Registry (ACR), it can act as a microservice in the cloud. There are many use cases for long-running services, and the Worker Service exists for this reason.
In this tutorial, you learn how to:
Create a worker service.
Create container registry resource.
Push an image to container registry.
Deploy as container instance.
Verify worker service functionality.
Tip
All of the "Workers in .NET" example source code is available in the Samples Browser for download. For more information, see Browse code samples: Workers in .NET.
To create a new Worker Service project with Visual Studio, select File > New > Project.... From the Create a new project dialog search for "Worker Service", and select Worker Service template. Enter the desired project name, select an appropriate location, and select Next. On the Additional information page, for the Target Framework select .NET 5.0, and check the Enable Docker option to enable docker support. Select the desired Docker OS.
To create a new Worker Service project with Visual Studio Code, you can run .NET CLI commands from the integrated terminal. For more information, see Visual Studio Code: Integrated Terminal.
Open the integrated terminal, and run the dotnet new command, and replace the <Project.Name> with your desired project name.
dotnet new worker --name <Project.Name>
For more information on the .NET CLI new worker service project command, see dotnet new worker.
To create a new Worker Service project with the .NET CLI, open your favorite terminal in a working directory. Run the dotnet new command, and replace the <Project.Name> with your desired project name.
dotnet new worker --name <Project.Name>
For more information on the .NET CLI new worker service project command, see dotnet new worker.
Build the application to ensure it restores the dependent packages, and compiles without error.
To build the application from Visual Studio, select F6 or select the Build > Build Solution menu option.
To build the application from Visual Studio Code, open the integrated terminal window and run the dotnet build command from the working directory.
dotnet build
For more information on the .NET CLI build command, see dotnet build.
To build the application from the .NET CLI, run the dotnet build command from the working directory.
dotnet build <path/to/project.csproj>
Specify your <path/to/project.csproj> value, which is the path to the project file to build. For more information on the .NET CLI build command, see dotnet build.
Add Docker support
If you correctly selected the Enable Docker checkbox when creating a new Worker project, skip to the Build the Docker image step.
If you didn't select this option, no worries—you can still add it now. In Visual Studio, right-click on the project node in the Solution Explorer, and select Add > Docker Support. You'll be prompted to select a Target OS; select OK with the default OS selection.
In Visual Studio Code, you need the Docker extension and the Azure Account extension installed. Open the Command Palette, and select the Docker: Add Docker files to workspace option. If prompted to Select Application Platform, choose .NET: Core Console. If prompted to Select Project, choose the Worker Service project you created. When prompted to Select Operating System, choose the first listed OS. When prompted whether or not to Include optional Docker Compose files, select No.
Docker support requires a Dockerfile. This file is a set of comprehensive instructions, for building your .NET Worker Service as a Docker image. The Dockerfile is a file without a file extension. The following code is an example Dockerfile, and should exist at the root directory of the project file.
With the CLI, the Dockerfile is not created for you. Copy its contents into a new file named Dockerfile in the root directory of the project.
FROM mcr.microsoft.com/dotnet/runtime:8.0@sha256:e6b552fd7a0302e4db30661b16537f7efcdc0b67790a47dbf67a5e798582d3a5 AS base
WORKDIR /app
# Creates a non-root user with an explicit UID and adds permission to access the /app folder
# For more info, please refer to https://aka.ms/vscode-docker-dotnet-configure-containers
RUN adduser -u 5678 --disabled-password --gecos "" appuser && chown -R appuser /app
USER appuser
FROM mcr.microsoft.com/dotnet/sdk:8.0@sha256:35792ea4ad1db051981f62b313f1be3b46b1f45cadbaa3c288cd0d3056eefb83 AS build
WORKDIR /src
COPY ["App.CloudService.csproj", "./"]
RUN dotnet restore "App.CloudService.csproj"
COPY . .
WORKDIR "/src/."
RUN dotnet build "App.CloudService.csproj" -c Release -o /app/build
FROM build AS publish
RUN dotnet publish "App.CloudService.csproj" -c Release -o /app/publish
FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "App.CloudService.dll"]
Note
You need to update the various lines in the Dockerfile that reference *App.CloudService—replace this with the name of your project.
Right-click on the Dockerfile in the Solution Explorer, and select Build Docker Image. The Output window displays, reporting the docker build command progress.
Right-click on the Dockerfile in the Explorer, and select Build Image. When prompted to Tag image as, enter appcloudservice:latest. The Docker Task output terminal displays, reporting the Docker build command progress.
Note
If you're not prompted to tag the image, it's possible that Visual Studio Code is relying on an existing tasks.json. If the tag used is undesirable, you can change it by updating the docker-build configuration item's dockerBuild/tag value in the tasks array. Consider the following example configuration section:
As the docker build command runs, it processes each line in the Dockerfile as an instruction step. This command builds the image and creates a local repository named appcloudservice that points to the image.
Tip
The generated Dockerfile differs between development environments. For example, if you Add Docker support from Visual Studio you may experience issues if you attempt to Build the Docker image from Visual Studio Code—as the Dockerfile steps vary. It is best to choose a single development environment and use it throughout this tutorial.
Create container registry
An Azure Container Registry (ACR) resource allows you to build, store, and manage container images and artifacts in a private registry. To create a container registry, you need to create a new resource in the Azure portal.
Select the Subscription, and corresponding Resource group (or create a new one).
Enter a Registry name.
Select a Location.
Select an appropriate SKU, for example Basic.
Select Review + create.
After seeing Validation passed, select Create.
Important
In order to use this container registry when creating a container instance, you must enable Admin user. Select Access keys, and enable Admin user.
An Azure Container Registry (ACR) resource allows you to build, store, and manage container images and artifacts in a private registry. Open a terminal window in the root directory of the Dockerfile, and run the following Azure CLI command:
Important
To interact with Azure resources from the Azure CLI, you must be authenticated for your terminal session. To authenticate, use the az login command:
az login
After you're logged in, use the az account set command to specify your subscription when you have more than one and no default subscription set.
az account set --subscription <subscription name or id>
Once you sign in to the Azure CLI, your session can interact with resources accordingly.
If you don't already have a resource group you'd like to associate your worker service with, create one using the az group create command:
az group create -n <resource group> -l <location>
Provide the <resource group> name, and the <location>. To create a container registry, call the az acr create command.
With the .NET Docker image built, and the container registry resource created, you can now push the image to container registry.
Right-click on the project in the Solution Explorer, and select Publish. The Publish dialog displays. For the Target, select Azure and then Next.
For the Specific Target, select Azure Container Registry and then Next.
Next, for the Container Registry, select the Subscription name that you used to create the ACR resource. From the Container registries selection area, select the container registry that you created, and then select Finish.
This creates a publish profile, which can be used to publish the image to container registry. Select the Publish button to push the image to the container registry, the Output window reports the publish progress—and when it completes successfully, you'll see a "Successfully published" message.
Select Docker from the Activity Bar in Visual Studio Code. Expand the IMAGES tree view panel, then expand the appcloudservice image node and right-click on the latest tag.
The integrated terminal window reports the progress of the docker push command to the container registry.
To push an image to the container registry, you need to sign in to the registry first:
az acr login -n <registry name>
The az acr login command signs into a container registry through the Docker CLI. To push the image to the container registry, use the az acr build command with your container registry name as the <registry name>:
az acr build -r <registry name> -t appcloudservice .
The preceding command:
Packs the source into a tar file.
Uploads it to the container registry.
The container registry unpacks the tar file.
Runs the docker build command in the container registry resource against the Dockerfile.
Adds the image to the container registry.
To verify that the image was successfully pushed to the container registry, navigate to the Azure portal. Open the container registry resource, under Services, select Repositories. You should see the image.
Deploy as container instance
From Visual Studio Code, select Docker from the Activity Bar. Expand the REGISTRIES node, and select Connect Registry. Select Azure when prompted, and sign in if necessary.
Expand the REGISTRIES node, select Azure, your subscription > the container registry > the image, and then right-click the tag. Select Deploy Image to Azure Container Instances.
To create a container instance, first create a container group using the az container create command.
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
.NET feedback
.NET is an open source project. Select a link to provide feedback:
Discover how to create a Docker image and store it in the Azure Container Registry, then use Azure App Service to deploy a web application based on the image.
Build end-to-end solutions in Microsoft Azure to create Azure Functions, implement and manage web apps, develop solutions utilizing Azure storage, and more.