.NET plugin (ubuntu@25.10)¶
The .NET plugin (ubuntu@25.10) builds .NET projects using the dotnet tool. It’s the successor to the .NET plugin (ubuntu@20.04).
Base support
This reference is for the .NET (ubuntu@25.10) plugin, which applies to base
ubuntu@25.10 or higher.
For base ubuntu@24.04 and lower, .NET parts build with the
.NET plugin (ubuntu@20.04).
Keys¶
This plugin provides the following unique keys.
dotnet-configuration¶
Type
DotnetConfiguration
Description
The .NET build configuration to use.
Values
Value |
Description |
|---|---|
|
Build with debug symbols and no optimizations. |
|
Build with optimizations and no debug symbols. This is the default configuration. |
dotnet-project¶
Type
str
Description
The path to the solution or project file to build, relative to the root of the snap source.
If a path isn’t specified, MSBuild will search the root of the source for a file
with the .*proj or .sln extension.
dotnet-properties¶
Type
dict[str, str]
Description
The MSBuild properties to append to the restore, build, and publish commands.
dotnet-self-contained¶
Type
bool
Description
Whether to create a self-contained .NET part.
The Runtime Identifier will be automatically set based on the value of the
$CRAFT_BUILD_FOR environment variable:
|
Runtime Identifier |
|---|---|
|
|
|
|
dotnet-verbosity¶
Type
DotnetVerbosity
Description
The verbosity of the MSBuild log.
Values
Value |
Description |
|---|---|
|
Show only errors. |
|
Alias for |
|
Show minimal build output. |
|
Alias for |
|
Show normal build output. This is the default level. |
|
Alias for |
|
Show detailed build output. |
|
Alias for |
|
Show diagnostic build output, the most verbose level. |
|
Alias for |
dotnet-version¶
Type
str
Description
The .NET version to build the part with.
If set, the plugin will download the necessary .NET SDK content snap and use it to build the app.
See Dependencies for a more detailed explanation of this key.
dotnet-restore-configfile¶
Type
str
Description
The path to the part’s NuGet configuration file.
If set, only the settings from this file will be used.
If unset, the hierarchy of configuration files from the current directory will be used. For more information, see Common NuGet Configurations.
dotnet-restore-properties¶
Type
dict[str, str]
Description
The MSBuild properties to append to the restore command.
dotnet-restore-sources¶
Type
list[str]
Description
The URIs of the NuGet package sources for use during a restore.
If set, the URIs override all of the sources declared in the nuget.config files.
dotnet-build-framework¶
Type
str
Description
The specific .NET framework to compile for.
The framework must be defined in the .NET project file.
Examples
dotnet-build-framework: net7.0
dotnet-build-framework: net462
dotnet-build-properties¶
Type
dict[str, str]
Description
The MSBuild properties to append to the build command, in the
format -p:<Key>=<Value>.
dotnet-publish-properties¶
Type
dict[str, str]
Description
The MSBuild properties to append to the publish command, in the
format -p:<Key>=<Value>.
Dependencies¶
The .NET plugin needs the .NET SDK to build programs. The SDK can be provisioned by the plugin itself, the build environment, or a previous part.
If dotnet-version is set, the plugin sources the .NET SDK from a Canonical .NET content snap. Content snaps are available for .NET 6 and newer, and the SDKs are compatible with Ubuntu 22.04 LTS and newer.
If dotnet-version is not set, the plugin assumes that the .NET SDK is already available in the build environment. This option is particularly useful when building on bases that don’t support the .NET SDK content snaps (e.g., Ubuntu 20.04).
The .NET SDK can be provided in the build environment with:
A .NET SDK package available from the Ubuntu archive, declared as a
build-package. Example: dotnet-sdk-8.0.A .NET SDK content snap, declared as a
build-snapfrom the desired channel. Example: dotnet-sdk-80.
Another alternative is to define a separate part called dotnet-deps and have your
application’s part build after the dotnet-deps part with the after key. In this
case, the plugin assumes that dotnet-deps will stage the .NET SDK to be used
during build. This can be useful in cases where a specific, unreleased version of .NET
is desired but unavailable as a snap or Ubuntu package.
This plugin validates the presence of .NET by running dotnet --version. Therefore,
it assumes that the dotnet executable is visible in the PATH. To achieve that, make sure
to append the location of the staged .NET SDK from dotnet-deps to the PATH using the
build-environment key in your application part.
See User-provided .NET SDK for an example of this approach.
Finally, whether the resulting build artifact will also need a .NET runtime installed in its environment depends on the value of the dotnet-self-contained key. Self-contained builds bundle the runtime in the generated executable and don’t require a global .NET Runtime installed in the system.
How it works¶
During the build step the plugin performs the following actions:
Call
dotnet restorewith the relevant global flags and restore-specific flags.Call
dotnet build --no-restorewith the relevant global flags and build-specific flags.Call
dotnet publish --no-restore --no-buildwith the relevant global and publication flags. The generated assets are placed in${CRAFT_PART_INSTALL}by default.
Examples¶
Plugin-provided .NET SDK¶
The following example uses the .NET (v2) plugin to build an application with .NET 8
using the debug configuration, generating assets that are self-contained. Since the
dotnet-version key is set, the plugin provisions the .NET SDK by itself.
parts:
my-dotnet-part:
source: .
plugin: dotnet
dotnet-version: "8.0"
dotnet-configuration: "Debug"
dotnet-self-contained: true
This is the simplest way to build a .NET application using the .NET (v2) plugin.
User-provided .NET SDK¶
The following example builds a .NET application with a custom user-provided .NET SDK.
By providing a dotnet-deps part, the plugin will not attempt to provision the .NET
SDK by itself and will instead rely on the user-provided SDK staged by the
dotnet-deps part.
parts:
dotnet-deps:
plugin: dump
source: https://builds.dotnet.microsoft.com/dotnet/Sdk/8.0.416/dotnet-sdk-8.0.416-linux-x64.tar.gz
source-checksum: sha512/633cb85673e3519c825532f780f6750ff24ed248ef8df68885540e510b559b6adc2c8d940e4c349fc0cf2c9caf184f1efeaccbc5e952d6e435f3da027cae4188
organize:
'*': dotnet-sdk/
prime:
- -dotnet-sdk/
my-dotnet-part:
after: [dotnet-deps]
source: .
plugin: dotnet
dotnet-configuration: "Release"
dotnet-self-contained: true
build-packages:
- libicu74
stage-packages:
- libicu74
build-environment:
- PATH: ${PATH}:${CRAFT_STAGE}/dotnet-sdk
There are a few important details to note in this example.
The dotnet-deps part uses the dump plugin to download and stage a version of the
.NET SDK from Microsoft’s official distribution site. To avoid polluting the root of the
stage directory, the organize key is used to place the contents of the SDK into a
dedicated subdirectory, called dotnet-sdk/ in this case. Then, in the
my-dotnet-part part, we append this subdirectory to the PATH with the
build-environment key so that the dotnet executable is visible during the build
step.
To prevent the .NET SDK from being included in the final artifact, the entire
dotnet-sdk/ subdirectory is removed with the prime key.
Note that we also need to include the libicu74 package in both the build and stage
steps, as it’s a dependency of the .NET SDK used during build and .NET Runtime used at
runtime.