Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Docs/pages/registration/05-keyed-services.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ public sealed class LatteRecipe([FromKey(MilkKind.Oat)] IMilk milk);
:::

:::caution[When not to reach for this]
Prefer distinct abstractions, or a [composite](./composites), over one service type selected by a key. A key is invisible to the type system, so nothing checks that a consumer asks for a key that exists. Reach for keys (and `WhenInjectedInto`) only when the implementations really are interchangeable variants of one abstraction, like the milk fridge above. Resolving the ambiguity with a key can hide a design that wants to be split into separate types, see [Principles](../principles#when-power-becomes-a-smell).
Prefer distinct abstractions, or a [composite](./composites), over one service type selected by a key. A key is invisible to the type system, so nothing checks that a consumer asks for a key that exists. Reach for keys (and `WhenInjectedInto`) only when the implementations really are interchangeable variants of one abstraction, like the milk fridge above. Resolving the ambiguity with a key can hide a design that wants to be split into separate types, see [Design principles](../design-principles#when-power-becomes-a-smell).
:::

## Want the whole set?
Expand Down
2 changes: 1 addition & 1 deletion Docs/pages/registration/07-scanning.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ An explicit registration of a scanned type wins over the scan, so you can specia
*Note: a scan that matches nothing is a warning ([AWT138](../diagnostics#awt138)), not an error, so an empty menu does not break the build.*

:::caution[When not to reach for this]
Prefer explicit registrations. A scan trades away the property that makes the composition root useful: the whole graph visible in one place. Reach for a scan only for a large, uniform family that grows on its own, like message handlers, validators, or plug-ins, where listing each one adds churn without adding clarity. For a handful of services, spell them out, see [Principles](../principles#when-power-becomes-a-smell).
Prefer explicit registrations. A scan trades away the property that makes the composition root useful: the whole graph visible in one place. Reach for a scan only for a large, uniform family that grows on its own, like message handlers, validators, or plug-ins, where listing each one adds churn without adding clarity. For a handful of services, spell them out, see [Design principles](../design-principles#when-power-becomes-a-smell).
:::

## Where to go next
Expand Down
2 changes: 1 addition & 1 deletion Docs/pages/resolution/05-property-injection.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ public sealed class Handler<T>
:::

:::caution[When not to reach for this]
Prefer constructor injection. A constructor parameter states a dependency plainly and cannot be forgotten; a property can be left unset. Reach for property injection only for a genuinely optional dependency with a sensible local default, or to break a cycle two constructors cannot. If you are using it to shorten a long constructor, that constructor is telling you the class does too much, see [Principles](../principles#when-power-becomes-a-smell).
Prefer constructor injection. A constructor parameter states a dependency plainly and cannot be forgotten; a property can be left unset. Reach for property injection only for a genuinely optional dependency with a sensible local default, or to break a cycle two constructors cannot. If you are using it to shorten a long constructor, that constructor is telling you the class does too much, see [Design principles](../design-principles#when-power-becomes-a-smell).
:::

## Where to go next
Expand Down
2 changes: 1 addition & 1 deletion Docs/pages/resolution/07-context-aware-factories.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ The other factory parameters resolve from the graph as usual. `[RequestingType]`
*Note: the parameter must be `System.Type` ([AWT162](../diagnostics#awt162)), and a factory cannot mix `[RequestingType]` with an `[Arg]` runtime argument ([AWT163](../diagnostics#awt163)).*

:::caution[When not to reach for this]
The requesting-type hook is advanced, and it makes one abstraction mean different things to different consumers, which is exactly the kind of implicit coupling DI is meant to remove. Reserve it for a genuinely cross-cutting service where the consumer's identity is the whole point, like a logger named after the class that uses it. For anything else, give each consumer the dependency it actually needs, see [Principles](../principles#when-power-becomes-a-smell).
The requesting-type hook is advanced, and it makes one abstraction mean different things to different consumers, which is exactly the kind of implicit coupling DI is meant to remove. Reserve it for a genuinely cross-cutting service where the consumer's identity is the whole point, like a logger named after the class that uses it. For anything else, give each consumer the dependency it actually needs, see [Design principles](../design-principles#when-power-becomes-a-smell).
:::

## Where to go next
Expand Down
2 changes: 1 addition & 1 deletion Tests/Awaiten.ExampleTests/ArchitectureTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
namespace Awaiten.ExampleTests;

/// <summary>
/// Architecture test from the "Principles &amp; the composition root" docs: domain and application
/// Architecture test from the "Design principles &amp; the composition root" docs: domain and application
/// code must never reference Awaiten. Only the composition root is allowed to. This turns the
/// convention into a red build the day someone crosses the line, even where AWT134 cannot see it.
/// </summary>
Expand Down
Loading