# Dovetail SDKs for each Microsoft SDK

# 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:

```xml
<!-- 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"`):

```json
{
    "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](../../guides/console-apps/). Nor is `Joinery.Dovetail.Sdk.ModularPipelines`: it is `Joinery.Dovetail.Sdk` plus
ModularPipelines, for [build pipelines](../../guides/modular-pipelines/) (`#:sdk Joinery.Dovetail.Sdk.ModularPipelines`).

## 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:

```xml
<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](../../reference/dovetail-host/)), 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

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:

```xml
<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`:

```c#
await using var app = await DistributedApplication.CreateBuilder(args).ConfigureDovetail();
await app.RunAsync();
```

```c#
// 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:

```c#
// 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

`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:

```bash
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:

```xml
<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:

```csharp
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>()`):

```csharp
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

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

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.