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.
The joint Chirograph declares
Section titled “The joint Chirograph declares”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
Includeis prefixed withChirograph., 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=falseturns the joints off for the project. See Properties.
A joint of your own
Section titled “A joint of your own”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.