Dovetail SDKs for each Microsoft SDK
Dovetail SDKs for each Microsoft SDK
Section titled “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 SDK | Dovetail SDK | What it is for |
|---|---|---|
Microsoft.NET.Sdk | Joinery.Dovetail.Sdk | Console apps, libraries and test projects |
Microsoft.NET.Sdk.Web | Joinery.Dovetail.Sdk.Web | ASP.NET Core applications |
Microsoft.NET.Sdk.Worker | Joinery.Dovetail.Sdk.Worker | Worker services |
Microsoft.NET.Sdk.Razor | Joinery.Dovetail.Sdk.Razor | Razor class libraries |
Microsoft.NET.Sdk.BlazorWebAssembly | Joinery.Dovetail.Sdk.BlazorWebAssembly | Blazor WebAssembly applications |
Microsoft.NET.Sdk.WebAssembly | Joinery.Dovetail.Sdk.WebAssembly | WebAssembly applications (the wasmbrowser template) |
Microsoft.NET.Sdk.WindowsDesktop | Joinery.Dovetail.Sdk.WindowsDesktop | Windows Forms and WPF projects that still name it |
Azure.Functions.Sdk | Joinery.Dovetail.Sdk.Azure.Functions | Azure 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).
What a Dovetail SDK does
Section titled “What a Dovetail SDK does”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.
Aspire AppHosts
Section titled “Aspire AppHosts”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();[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:
[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
Section titled “Azure Functions”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:
dotnet build -p:DovetailAzureFunctionsSdkVersion=1.2.0Azure.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.