Skip to content

Dovetail SDKs for each Microsoft SDK

Each Microsoft project SDK has a Dovetail SDK of the same name. To give a project Dovetail, change its SDK name and nothing else:

<!-- before -->
<Project Sdk="Microsoft.NET.Sdk.Web">
<!-- after -->
<Project Sdk="Joinery.Dovetail.Sdk.Web">

Pin the version in global.json under msbuild-sdks, or put it in the attribute (Sdk="Joinery.Dovetail.Sdk.Web/1.2.3"):

{
"msbuild-sdks": {
"Joinery.Dovetail.Sdk.Web": "1.2.3"
}
}
Microsoft SDKDovetail SDKWhat it is for
Microsoft.NET.SdkJoinery.Dovetail.SdkConsole apps, libraries and test projects
Microsoft.NET.Sdk.WebJoinery.Dovetail.Sdk.WebASP.NET Core applications
Microsoft.NET.Sdk.WorkerJoinery.Dovetail.Sdk.WorkerWorker services
Microsoft.NET.Sdk.RazorJoinery.Dovetail.Sdk.RazorRazor class libraries
Microsoft.NET.Sdk.BlazorWebAssemblyJoinery.Dovetail.Sdk.BlazorWebAssemblyBlazor WebAssembly applications
Microsoft.NET.Sdk.WebAssemblyJoinery.Dovetail.Sdk.WebAssemblyWebAssembly applications (the wasmbrowser template)
Microsoft.NET.Sdk.WindowsDesktopJoinery.Dovetail.Sdk.WindowsDesktopWindows Forms and WPF projects that still name it
Azure.Functions.SdkJoinery.Dovetail.Sdk.Azure.FunctionsAzure Functions isolated worker applications

Joinery.Dovetail.Sdk.Console is not a mirror: it is Joinery.Dovetail.Sdk plus a generated Program.cs for console applications. Nor is Joinery.Dovetail.Sdk.ModularPipelines: it is Joinery.Dovetail.Sdk plus ModularPipelines, for build pipelines (#:sdk Joinery.Dovetail.Sdk.ModularPipelines).

Joinery.Dovetail.Sdk.Web imports Microsoft.NET.Sdk.Web, then chains Joinery.Dovetail.Sdk. That is the same thing as naming both yourself:

<Project Sdk="Microsoft.NET.Sdk.Web">
<Sdk Name="Joinery.Dovetail.Sdk" Version="1.2.3" />
</Project>

So the project builds exactly as it did with the Microsoft SDK. On top of that, Joinery.Dovetail.Sdk detects the host from what the Microsoft SDK set (see DovetailHost), adds the Dovetail packages the project needs, and emits the bootstrapping.

The others work the same way. Microsoft.NET.Sdk.WindowsDesktop has been unnecessary since .NET 5 (the SDK warns NETSDK1137): Microsoft.NET.Sdk with UseWPF or UseWindowsForms is enough, and so is Joinery.Dovetail.Sdk. Its mirror is for projects that have not moved off it yet.

There is no Aspire SDK to mirror any more. Since Aspire 17 a C# AppHost is Microsoft.NET.Sdk with the Aspire.Hosting.AppHost and Aspire.Hosting.Dotnet packages, and Aspire.AppHost.Sdk is obsolete (ASPIRE012). So an AppHost swaps Microsoft.NET.Sdk for Joinery.Dovetail.Sdk, like any other project, and keeps its Aspire packages:

<Project Sdk="Joinery.Dovetail.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Aspire.Hosting.AppHost" Version="17.0.0" />
<PackageReference Include="Aspire.Hosting.Dotnet" Version="17.0.0" />
</ItemGroup>
</Project>

Aspire.Hosting.AppHost sets IsAspireHost itself. Add .NET projects as resources with AddDotnetProject: without Aspire.AppHost.Sdk, a project reference no longer generates Projects.* metadata. Builds resolve the Aspire CLI (ASPIRE009 when they can’t), so install it alongside, at the same version as the packages.

An AppHost is detected as such: a project that references Aspire.Hosting.AppHost gets Joinery.Dovetail.Aspire and the DistributedApplication host in place of the generic host, so ConfigureDovetail extends IDistributedApplicationBuilder. It applies the IDistributedApplicationBuilderJoint joints of the AppHost and of the assemblies it references, in dependency order, then builds the application, so the resources can come from joints instead of Program.cs:

await using var app = await DistributedApplication.CreateBuilder(args).ConfigureDovetail();
await app.RunAsync();
sample/SdkSample/SdkSample.AppHost/WebResourceJoint.cs
[DovetailExport]
public sealed class WebResourceJoint : IDistributedApplicationBuilderJoint
{
/// <inheritdoc />
public void Register(IDovetailContext context, IDistributedApplicationBuilder builder)
{
var web = builder
.AddDotnetProject("web", "../SdkSample.Web/SdkSample.Web.csproj")
.WithExternalHttpEndpoints()
.WithHttpHealthCheck("/health");
context.Set(new WebResource(web));
}
}

A joint that needs another’s resource runs after it, and finds the resource in the context:

sample/SdkSample/SdkSample.AppHost/WorkerResourceJoint.cs
[DovetailExport]
[DependsOnJoint<WebResourceJoint>]
public sealed class WorkerResourceJoint : IDistributedApplicationBuilderJoint
{
/// <inheritdoc />
public void Register(IDovetailContext context, IDistributedApplicationBuilder builder)
{
var web = context.Get<WebResource>()
?? throw new InvalidOperationException($"{nameof(WebResourceJoint)} has not added the web resource.");
builder
.AddDotnetProject("worker", "../SdkSample.Worker/SdkSample.Worker.csproj")
.WithReference(web.Builder)
.WaitFor(web.Builder);
}
}

The joint is in Joinery.Dovetail.Aspire, which any project that references Aspire.Hosting gets, so a library can ship resources to every AppHost that references it. The AppHost’s helper applies only these joints and the DistributedApplication host-created ones: an AppHost has no services or configuration of its own for joints to add to. DovetailEnableAspire=false leaves Aspire out (the AppHost is a generic host again), DovetailAspireHost=false only the host.

The services an AppHost runs are ordinary Dovetail applications. Aspire’s “service defaults” fit in a library of joints that each service references, with nothing to call: sample/SdkSample/SdkSample.ServiceDefaults turns on OpenTelemetry with the OTLP exporter (an IOpenTelemetryJoint) and service discovery with health checks (an IServiceJoint). The whole sample, an AppHost that runs SdkSample.Web and SdkSample.Worker, is in sample/SdkSample (mise run sample:aspire).

Joinery.Dovetail.Sdk.Aspire.AppHost, the mirror of Aspire.AppHost.Sdk, is no longer published. A project that used it switches to Joinery.Dovetail.Sdk as above.

Azure.Functions.Sdk is the MSBuild SDK for Azure Functions isolated worker applications, and it comes from NuGet. Joinery.Dovetail.Sdk.Azure.Functions imports it at the version it was built against, unless DovetailAzureFunctionsSdkVersion says otherwise. The Functions SDK is imported before any of the project’s files, so set that property where MSBuild sees it first, as an environment variable or on the command line:

Terminal window
dotnet build -p:DovetailAzureFunctionsSdkVersion=1.2.0

Azure.Functions.Sdk leaves Microsoft.Azure.Functions.Worker, the isolated worker every Functions application needs, to the application. Joinery.Dovetail.Sdk.Azure.Functions adds it for you, as an implicit package reference at the version it was built against (DovetailAzureFunctionsWorkerVersion picks another), so a project only references its trigger and binding extensions:

<Project Sdk="Joinery.Dovetail.Sdk.Azure.Functions">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" Version="2.1.1" />
</ItemGroup>
</Project>

A project that references Microsoft.Azure.Functions.Worker itself keeps its own reference and version, and the SDK adds nothing. Do that when an extension needs a newer worker than the SDK’s, since NuGet reports a package downgrade (NU1605) for the implicit one. With central package management, a PackageVersion for the worker in Directory.Packages.props sets the version of the implicit reference.

Azure.Functions.Sdk brings Microsoft.NET.Sdk.Worker, so the application is a generic host (HostApplication). It also gets the FunctionsApplication host, whose ConfigureDovetail extends the FunctionsApplicationBuilder that FunctionsApplication.CreateBuilder returns:

using Microsoft.Azure.Functions.Worker.Builder;
var host = await FunctionsApplication.CreateBuilder(args).ConfigureDovetail();
await host.RunAsync();

FunctionsApplicationBuilder is both an IHostApplicationBuilder and an IFunctionsWorkerApplicationBuilder, so the host application joints for either run on it. A library that adds worker middleware declares a joint for the worker builder, and the context carries the builder under that type too (context.Get<IFunctionsWorkerApplicationBuilder>()):

using System.Threading.Tasks;
using Joinery.Dovetail;
using Joinery.Dovetail.Attributes;
using Joinery.Dovetail.Joints;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Middleware;
using Microsoft.Extensions.Hosting;
[DovetailExport]
public class CorrelationJoint : IHostApplicationJoint<IFunctionsWorkerApplicationBuilder>
{
public void Register(IDovetailContext context, IFunctionsWorkerApplicationBuilder builder) =>
builder.UseMiddleware<CorrelationMiddleware>();
}
public class CorrelationMiddleware : IFunctionsWorkerMiddleware
{
public Task Invoke(FunctionContext context, FunctionExecutionDelegate next) => next(context);
}

A project on the older Microsoft.Azure.Functions.Worker.Sdk package (Microsoft.NET.Sdk with an Exe and a reference to Microsoft.Azure.Functions.Worker) gets the FunctionsApplication host from Joinery.Dovetail.Sdk the same way.

Choosing the version of Joinery.Dovetail.Sdk

Section titled “Choosing the version of Joinery.Dovetail.Sdk”

A Dovetail SDK chains the Joinery.Dovetail.Sdk of its own version: every Dovetail package ships at one version. To chain another, set DovetailSdkVersion in a Directory.Build.props. The Microsoft SDK imports that file before the Dovetail SDK reads the property.

With Joinery.Dovetail.Sdk in a Directory.Build.props

Section titled “With Joinery.Dovetail.Sdk in a Directory.Build.props”

A repository that applies Joinery.Dovetail.Sdk to every project from a Directory.Build.props can still switch a project to a Dovetail SDK. The Dovetail SDK sees that Joinery.Dovetail.Sdk is already there and does not apply it a second time.