Skip to content

With Dovetail

Dovetail registers services through joints: classes the host finds at build time and runs when ConfigureDovetail() builds it. Chirograph never references Dovetail. Every client gets a plain Add<ClientName>() registration, and a joint is one more caller of it.

Dovetail has an extension point for packages that ship C#: a DovetailTemplate item, which Dovetail expands into a file only in projects that run its source generator. Chirograph declares one per client. For the client RocketsClient in MyApp.Rockets it is:

<DovetailTemplate Include="Chirograph.RocketsClient"
File="…/Sdk/templates/OpenApiClientJoint.cs.template"
ClientName="RocketsClient"
Namespace="MyApp.Rockets"
ChirographVersion="…" />

Dovetail writes it as obj/…/DovetailTemplate.Chirograph.RocketsClient.g.cs, with each __Name__ token replaced by the metadata of the same name:

namespace MyApp.Rockets;
[DovetailExport]
internal sealed class RocketsClientJoint : IServiceJoint
{
public void Register(IDovetailContext context, IServiceCollection services) =>
global::MyApp.Rockets.RocketsClientServiceCollectionExtensions.AddRocketsClient(services);
}

So the client resolves from a host built with ConfigureDovetail(), with no registration call of your own:

using var host = await Host.CreateApplicationBuilder(args).ConfigureDovetail();
var client = host.Services.GetRequiredService<RocketsClient>();
  • The items are declared only when the Dovetail in the build sets DovetailTemplateMetadataTokens, the capability property that release added. An older Dovetail never gets a template it can’t expand.
  • The Include is prefixed with Chirograph., so it can’t clash with another package’s template for a type of the same name.
  • Dovetail writes the joint only into a project that runs its source generator. A library that generates a client and references Dovetail exports the joint to every application that references it, as any exported joint is.
  • ChirographGenerateDovetailJoint=false turns the joints off for the project. See Properties.

Turn the generated joints off and write your own when you want to configure the client further, on the builder the registration returns, or when your Dovetail is older than the release above:

[DovetailExport]
public sealed class RocketsClientSetup : IServiceJoint
{
public void Register(IDovetailContext context, IServiceCollection services) =>
services.AddRocketsClient().AddStandardResilienceHandler();
}

AddStandardResilienceHandler() comes from Microsoft.Extensions.Http.Resilience, as an example of chaining on the IHttpClientBuilder. Don’t name your joint <ClientName>Joint in the client’s namespace while the generated joints are on: that is the name of the generated one.