.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

Debug

Build with debug symbols and no optimizations.

Release

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:

$CRAFT_BUILD_FOR value

Runtime Identifier

amd64

linux-x64

arm64

linux-arm64

dotnet-verbosity

Type

DotnetVerbosity

Description

The verbosity of the MSBuild log.

Values

Value

Description

quiet

Show only errors.

q

Alias for quiet.

minimal

Show minimal build output.

m

Alias for minimal.

normal

Show normal build output. This is the default level.

n

Alias for normal.

detailed

Show detailed build output.

d

Alias for detailed.

diagnostic

Show diagnostic build output, the most verbose level.

diag

Alias for diagnostic.

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-snap from 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:

  1. Call dotnet restore with the relevant global flags and restore-specific flags.

  2. Call dotnet build --no-restore with the relevant global flags and build-specific flags.

  3. Call dotnet publish --no-restore --no-build with 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.

Project file
  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.

Project file
  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.