Docs menu

Customizing the build

Customize the .NET build on Primcloud: MSBuild targets, build settings, native dependencies, and system packages.

On this page

Most .NET apps need no custom build steps. When yours does, use MSBuild targets, build settings, or system packages.

Build hooks#

Add steps before or after publishing with MSBuild targets in your project file. They run during dotnet publish, so your local and Primcloud builds behave the same.

Run a command before publish:

MyApp.csproj
<Target Name="RunPreBuildScript" BeforeTargets="Publish">
  <Exec Command="./scripts/pre-publish.sh" />
</Target>

Run a command after publish:

MyApp.csproj
<Target Name="StampBuildInfo" AfterTargets="Publish">
  <WriteLinesToFile File="$(PublishDir)/BUILD_SHA" Lines="$(BUILD_SHA)" Overwrite="true" />
</Target>

$(PublishDir) is bin/publish on Primcloud. Your secrets are available to <Exec> as $(VarName).

Build settings#

Choose the solution, MSBuild configuration, and verbosity in a project.toml at the root of your repo:

project.toml
[_]
schema-version = "0.2"

[com.heroku.buildpacks.dotnet]
solution_file = "MyWebApp.sln"

[com.heroku.buildpacks.dotnet.msbuild]
configuration = "Release"
verbosity = "normal"

Or with secrets, which take precedence over project.toml:

  • SOLUTION_FILE: the solution file to build.
  • BUILD_CONFIGURATION: MSBuild configuration; defaults to Release.
  • MSBUILD_VERBOSITY_LEVEL: MSBuild verbosity; defaults to minimal.

Set any other MSBuild properties in your project file or a Directory.Build.props.

Native dependencies#

NuGet packages with native code, like SkiaSharp or Microsoft.Data.SqlClient, include their Linux binaries in the package and work with no setup.

System libraries your code calls through P/Invoke, or that a package links against, like libgdiplus or libmariadb, come from system packages, below.

Debian packages#

When your app needs system libraries or command-line tools that aren't already installed, list them in a project.toml at the root of your repo:

project.toml
[_]
schema-version = "0.2"

[com.heroku.buildpacks.deb-packages]
install = [
  "libgdiplus",
  "libmariadb-dev",
]

Each entry is a package name from the Ubuntu 24.04 archive. Its programs and libraries are available during the build and at runtime.

Advanced options (rarely needed):

  • Skip a package's dependencies: { name = "some-package", skip_dependencies = true }
  • Force a reinstall: { name = "some-package", force = true }
  • Install from a URL: download = ["https://example.com/package-1.2.3.deb"]
  • Add a package repository: a [[com.heroku.buildpacks.deb-packages.sources]] table with uri, suites, components, arch, and signed_by (the repository's key as an ASCII-armored PGP block).

Note

The build doesn't read an Aptfile. If your repo has one, the build log warns you and nothing in it is installed. Move the packages into project.toml as shown above.