# DovetailJoint # DovetailJoint A `DovetailJoint` item declares a **joint kind**: a typed extension point that other code can contribute to without knowing who applies it. One line in a project file becomes a joint interface, its async twin, the delegates for both, an `Apply` extension that runs every joint of the kind, and a method on `DovetailContextBuilder` that registers a delegate. Dovetail's own joints (`ISetupJoint`, `IServiceJoint`, `ILoggingJoint`, `IConfigurationJoint`, `IHostCreatedJoint`) are declared this way, and so are those of [Serilog](../../concepts/serilog/), [OpenTelemetry](../../concepts/opentelemetry/) and Aspire. The item is expanded by MSBuild targets, not by the Roslyn source generator: the C# is written to `obj/` before the compiler runs, so you can open it in your IDE like any other source file. ## Who declares one, and when A package or application that owns something other code should be able to configure declares a joint kind for it. Serilog's package declares `Serilog` for `LoggerConfiguration`, so any library can add a sink; `Sample.Core` declares `DatabaseConfigurator` for its own `IDatabaseConfigurator`, so other assemblies can add tables and views. Declare one when: - you hand an object to other code at one point in startup (a builder, a configuration object) and want every library to be able to contribute to it without referencing your application or each other; - you are prepared to call `Apply{Name}` yourself at that point. A joint kind does not run by itself: `SerilogJoint` calls `loggerConfiguration.ApplySerilog(...)` once it has created the `LoggerConfiguration`. Do not declare one when: - you only want to run code at startup. Implement an existing joint such as `IServiceJoint` or `ILoggingJoint` instead, as described in [Defining Dovetails](../../concepts/defining-joints/); - Dovetail or one of its packages already declares a joint for the type you have: `Joinery.Dovetail` covers `IServiceCollection`, `IConfigurationBuilder` and `ILoggingBuilder`, and `Joinery.Dovetail.Hosting` covers the host builders. The item is read by the targets that ship in `Joinery.Dovetail`, so the project that declares it must reference that package (`Joinery.Dovetail.Sdk` adds the reference for you). The generated types are `public`, so anything that references your project sees them as ordinary API. ## Declaring a joint The item's `Include` is the joint's name. It becomes part of every generated type name, and of the generated file names, so it has to be a valid C# identifier, and it must be unique in the project. ```xml ``` That is the smallest useful declaration: a joint that is handed only the `IDovetailContext`. Everything else is metadata. ## Metadata Metadata is optional unless stated. A name the item does not read is ignored without a warning, so a misspelling falls back to the default (`NMAmespace` leaves `Namespace` at its default). Boolean values are compared with `true` ignoring case; any other non-empty value counts as false. | Metadata | Default | What it changes | | ---------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Namespace` | `$(RootNamespace).Joints` | The namespace of every generated type, and so the namespace consumers import. Joints of one package usually share one, as `Joinery.Dovetail.Joints` does. | | `ProvideConfiguration` | empty (false) | `true` adds an `IConfiguration configuration` parameter to `Register`, after the context. The value passed is `context.Configuration`; `Apply{Name}` takes no configuration parameter. | | `ProvideServices` | empty (false) | `true` adds an `IServiceCollection services` parameter to `Register`, after the configuration if there is one. With no `ParameterType` it is also the subject of `Apply{Name}`. | | `ParameterType` | empty | The type of one more `Register` parameter, the last one. It becomes the subject of `Apply{Name}`. Written into the generated code exactly as given; see [common mistakes](#common-mistakes). | | `ParameterName` | `parameter` when `ParameterType` is set | The name of that parameter, as it appears in `Register` and in `Apply{Name}`. Ignored without `ParameterType`. | | `BuilderMethodName` | `Configure{Name}` | The name of the extension method on `DovetailContextBuilder` that registers a delegate. `Service` is declared with `BuilderMethodName="ConfigureServices"`. | | `GenericParameter` | empty | A type parameter name that makes the joint generic: `I{Name}Joint`, `Apply{Name}`, `Configure{Name}`. `ParameterType` may be this name, and then the parameter is typed `T`. | | `GenericConstraint` | empty | The constraint of that type parameter: `where T : {GenericConstraint}`. Written as given. Ignored without `GenericParameter`. | | `GenericVariance` | `in` when `GenericParameter` is set | The variance modifier on the type parameter of the generated interfaces and delegates. Ignored without `GenericParameter`. When `ParameterType` is the type parameter, only `in` compiles; see [common mistakes](#common-mistakes). | | `IsAsync` | `true` | `false` generates only the synchronous joint. No `I{Name}AsyncJoint`, `{Name}AsyncJointDelegate` or async `Configure{Name}` overload, no `DovetailJointAsync.{Name}.g.cs`, and `Apply{Name}` returns `void` instead of `ValueTask`. | | `ReturnFirstArgument` | empty (false) | `true` makes `Apply{Name}` return `ValueTask`, the context after the joints ran. It compiles only for a joint whose subject is the context itself: no `ParameterType` and no `ProvideServices`. With `IsAsync` false the result is discarded. | ### The parameter lists `Register` takes, in this order, only the parameters that apply: 1. `IDovetailContext context`, always; 2. `IConfiguration configuration`, with `ProvideConfiguration`; 3. `IServiceCollection services`, with `ProvideServices`; 4. `{ParameterType} {ParameterName}`, with `ParameterType`; 5. `CancellationToken cancellationToken = default`, in the async twin only. `Apply{Name}` is an extension method. Its subject (the `this` parameter) is the `ParameterType` if there is one, otherwise the service collection if `ProvideServices` is set, otherwise the context. After the subject come the context (unless it is the subject), the service collection (if `ProvideServices` and `ParameterType` are both set) and, last, a `CancellationToken cancellationToken = default`. ## What is generated Each joint is written to `$(IntermediateOutputPath)`, which is `obj///`, as ordinary `Compile` items: | File | Contents | | -------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `DovetailJoint.{Name}.g.cs` | `I{Name}Joint`, its delegate, `Apply{Name}` and the `Configure{Name}` method for the delegate. | | `DovetailJointAsync.{Name}.g.cs` | `I{Name}AsyncJoint`, its delegate and the `Configure{Name}` method for it. Not written when `IsAsync` is false. | Everything is declared in `Namespace`: | Type | What it is | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `I{Name}Joint` | The interface a contributor implements: `void Register(...)`. Mark the class `[DovetailExport]` so it is discovered; see [Defining Dovetails](../../concepts/defining-joints/). | | `{Name}JointDelegate` | A delegate with the same parameters, for registering a lambda. | | `I{Name}AsyncJoint` | The async twin: `ValueTask Register(..., CancellationToken cancellationToken = default)`. | | `{Name}AsyncJointDelegate` | The async delegate. | | `{Name}JointExtensions` | A static partial class holding `Apply{Name}`, which runs every registered `I{Name}Joint` and `I{Name}AsyncJoint` through the executor. | | `{Name}HostBuilderExtensions` | A static partial class with an `extension(DovetailContextBuilder)` block: `Configure{Name}(delegate, priority = 0, category = null, hostType = Undefined)`, once for each delegate type. Generated for every joint, including the ones whose subject is the context. | The interfaces derive from `IDovetailJoint` and, like the delegates, carry `[JointName("{Name}")]`. For the Serilog declaration [below](#a-joint-with-a-parameter-services-and-its-own-namespace), the build writes this (abridged from `obj/Debug/net10.0/DovetailJoint.Serilog.g.cs`, which also holds the attributes, the XML comments and the method bodies): ```c# namespace Joinery.Dovetail.Joints; public interface ISerilogJoint : global::Joinery.Dovetail.Infrastructure.IDovetailJoint { void Register(global::Joinery.Dovetail.IDovetailContext context, global::Microsoft.Extensions.DependencyInjection.IServiceCollection services, global::Serilog.LoggerConfiguration loggerConfiguration); } public delegate void SerilogJointDelegate(global::Joinery.Dovetail.IDovetailContext context, global::Microsoft.Extensions.DependencyInjection.IServiceCollection services, global::Serilog.LoggerConfiguration loggerConfiguration); public static partial class SerilogJointExtensions { public static global::System.Threading.Tasks.ValueTask ApplySerilog(this global::Serilog.LoggerConfiguration loggerConfiguration, global::Joinery.Dovetail.IDovetailContext context, global::Microsoft.Extensions.DependencyInjection.IServiceCollection services, global::System.Threading.CancellationToken cancellationToken = default); } public static partial class SerilogHostBuilderExtensions { extension(DovetailContextBuilder container) { public global::Joinery.Dovetail.DovetailContextBuilder ConfigureSerilog(SerilogJointDelegate @delegate, int priority = 0, DovetailCategory? category = null, DovetailHostType hostType = DovetailHostType.Undefined, [CallerArgumentExpression(nameof(@delegate))] string? expression = null); } } ``` ## Examples ### Minimal The `Setup` declaration [above](#declaring-a-joint) generates `ISetupJoint`, `SetupJointDelegate`, `ISetupAsyncJoint`, `SetupAsyncJointDelegate`, `SetupJointExtensions.ApplySetup(this IDovetailContext context, CancellationToken cancellationToken = default)` and `ConfigureSetup(...)`, all in `Joinery.Dovetail.Joints`. ### Leaving out `Namespace` Left out, `Namespace` is `$(RootNamespace).Joints`. This project sets `RootNamespace` to `Joinery.Dovetail`, so the joint's types are in `Joinery.Dovetail.Joints`: ```xml ``` ### A joint with a parameter, services and its own namespace `Joinery.Dovetail.Serilog` hands every Serilog joint the context, the service collection and the logger configuration: ```xml ``` The package applies the kind once it has built the `LoggerConfiguration` (`src/Joinery.Dovetail.Serilog/SerilogJoint.cs`): ```c# var loggerConfiguration = new global::Serilog.LoggerConfiguration(); await loggerConfiguration.ApplySerilog(context, services, cancellationToken).ConfigureAwait(false); ``` and anyone contributes by implementing `ISerilogJoint` or calling `ConfigureSerilog`, as shown in [Serilog](../../concepts/serilog/#the-serilog-joint). ### A joint in an application `Sample.Core` declares a joint kind for the object it hands to other assemblies, and applies it from a joint of its own: ```xml ``` ```c# // sample/Sample.Core/Databases/DatabaseServiceDovetail.cs [DovetailExport] public class DatabaseServiceJoint : IServiceAsyncJoint { public async ValueTask Register(IDovetailContext context, IServiceCollection services, CancellationToken cancellationToken = default) { var configurator = new DatabaseConfigurator(); await configurator.ApplyDatabaseConfigurator(context, cancellationToken: cancellationToken); } } ``` ### A generic joint `Joinery.Dovetail.Hosting` declares one joint for every host builder. `ParameterType` is the generic parameter, and, with no `GenericVariance`, the interface is contravariant, so `IHostApplicationJoint` runs for every host whose builder is one: ```xml ``` `Joinery.Dovetail` uses the same shape for `HostCreated`, with `GenericParameter="THost"`. ### The rarely needed values Nothing in `src/` or `sample/` sets `ProvideConfiguration`, `GenericConstraint`, `IsAsync` or `ReturnFirstArgument`, so these declarations are compiled, and the signatures they generate checked, by `test/Joinery.Dovetail.Sdk.Tests/DovetailItemReferenceTests.cs` (it declares exactly these items): ```xml ``` - `Minimal` is handed only the context, and its types are in `worker.Joints` (the test project's `RootNamespace` is `worker`). - `Wired` registers `Register(IDovetailContext context, IConfiguration configuration, IServiceCollection services)`, and its `ApplyWired` is an extension on `IServiceCollection`. - `Builder` is applied with `logging.ApplyBuilder(context, services)` and registered with `ConfigureTheBuilder(...)`. - `Generic` declares `IGenericJoint where TBuilder : IHostApplicationBuilder`. - `Covariant` has a type parameter that `Register` does not take, so `out` compiles, and an `ICovariantJoint` is an `ICovariantJoint