ConsumingEverything a script that receives dependencies uses.

Injecting

InjectAttribute

attrsealed

Marks a field or property to be injected with a dependency of its type. On a class, it marks every settable reference-type member of that class; on an assembly, every such member of every class in it. A member takes each option from its own attribute, else from its class's, else from its assembly's, else from the Inject by Default setting while it's enabled. An option nobody sets is off, and setting one to false turns off an inherited one. A subclass does not inherit the attribute from its base class.

Options
bool Optional { get; set; }Whether a missing dependency is accepted. The member keeps its default (its initializer, else null) and nothing fails.
bool Manual { get; set; }Whether the member is injected only by Manual.Inject, never automatically.
bool EditMode { get; set; }Whether the member is also injected in Edit mode, for [ExecuteAlways] components, ScriptableObjects and Editor tools. Otherwise it is injected only in Play mode and in builds.
bool Overwrite { get; set; }Whether the member is injected over a value it already holds. That value becomes the default the member returns to when its dependency is released or lost.
bool Async { get; set; }Whether the dependency can take several frames to arrive. The member keeps its current value until it does.
bool Reactive { get; set; }Whether the member is kept up to date. When its dependency is replaced, the new one is injected in its place, and a property receives it through its setter.
bool Warm { get; set; }Whether candidates are prepared ahead of time in the background, so the member receives a ready dependency at once instead of waiting or missing.
bool Weak { get; set; }Whether the member holds its dependency without keeping it alive. Use it when two objects Selvage created hold each other, so that both can end. When the dependency ends, the member returns to its default.

DontInjectAttribute

attrsealed

Excludes a field, property, class or assembly from injection. On a class or an assembly, it also excludes every member it covers. An [Inject] on the same scope or an inner one wins, and options set outside an excluded class or assembly do not apply inside it.

Manual

static

Injects, reinjects and releases a context's members from code. Works on every member, automatic or not; a member marked Manual is injected only through Inject. Call it on the Unity main thread, and pass a Type as the context to act on the static members of a class.

Static methods
In the Editor and in development builds, every method throws ArgumentNullException when the context is null, and ArgumentException when it is a value type. Every method throws InvalidOperationException when called while Unity creates an object: from a constructor or a field initializer.
SelvageOperation Inject(object context)Injects every member of the context that is not injected yet. Automatic members keep their usual timing: outside Play mode, only EditMode members are injected. Called before the context's automatic injection, it injects the automatic members early. Returns the combined operation of the members it injected, which a required member left null fails.
SelvageOperation Inject(object context, string memberName)Injects the named member, unless it is already injected. Outside Play mode, a member without EditMode is not injected: a required one fails the operation, an optional one is left as it is. Throws ArgumentException when the context has no field or property by that name, the name is ambiguous, or the member cannot be injected (a readonly field, a get-only property, an indexer, or a value-typed member).
SelvageOperation Reinject(object context)Reinjects every injected member of the context, replacing each dependency with a newly provided one. Members that are not injected are skipped. Inside a local block (Injector.Local), the members also get that block's dependencies.
SelvageOperation Reinject(object context, string memberName)Reinjects the named member. Does nothing when it is not injected. Throws ArgumentException in the same cases as Inject(context, memberName).
SelvageOperation Release(object context)Releases the context, as its Dispose or OnDestroy does. Every injected member returns to its default, Context.Released is raised, Context.IsReady returns false, and a pending Context.WhenReady is canceled. The context itself stays alive, and the next Inject starts a new injection. Returns the release's operation, already complete when everything released synchronously.
SelvageOperation Release(object context, string memberName)Releases the named member, returning it to its default. Does nothing when it is not injected. The context's injection does not end, so Context.Released is not raised and its readiness does not change. Throws ArgumentException in the same cases as Inject(context, memberName).

Context

static

Readiness queries and events for contexts. Call the queries on the Unity main thread, and pass a Type as the context to act on the static members of a class. The events are raised on the Unity main thread, for every context. A handler that throws is logged, and the remaining handlers still run. A handler that stores a context in a field keeps it alive: hold it weakly, or drop it on Released.

Static methods
In the Editor and in development builds, each method throws ArgumentNullException when the context is null, and ArgumentException when it is a value type.
SelvageOperation WhenReady(object context, float withinSeconds = 120)Returns an operation that completes once the context is ready, without injecting it. A context with no dependencies completes at once. A context not injected yet completes once it injects itself, or is canceled when it is released or destroyed first. A context not ready within withinSeconds of real time fails this wait with a TimeoutException, logged if nothing observes it, while the context keeps injecting. Zero requires it to be ready now; float.PositiveInfinity waits without a limit. To stop waiting without an error, use DetachAfter.
bool IsReady(object context)Returns true once the context's automatic injection has succeeded, and false while it is pending or after it failed. Cheap enough to call every frame. To tell a failure from a pending injection, read the Status of WhenReady.
Static events
event Action<object, SelvageOperation> InjectedRaised when a context is injected, automatically or by Manual.Inject, once its synchronous members are injected. The operation completes once its asynchronous dependencies are ready, and a required member left null fails it. Raised once per injection: not on a reinjection, and again only after the context is released and injected anew.
event Action<object> ReleasedRaised when a whole context is released: by its OnDestroy, its Dispose or DisposeAsync, Manual.Release, or the end of the owned dependency it is. It holds no dependency any more and can be injected again. A plain object's members are back to their defaults; a destroyed Unity object's members keep their last values.

Operations

SelvageOperation

sealed

Result of an injection, a reinjection, a release or a readiness query, returned by Manual and Context.WhenReady. await it, yield return it in a coroutine, or observe it from several subscribers. It completes at once when everything finished synchronously, and otherwise stays Running until the asynchronous work finishes. A yield in a coroutine cannot throw, so check Status or call ThrowIfNotSucceeded after it. A failure nobody observes is logged.

Properties
OperationStatus Status { get; }The current outcome of the operation. Reading it counts as observing the operation, so a failure it carries is not logged.
Exception Exception { get; }The failure of a Failed operation, or null otherwise. Reading it counts as observing the operation.
bool IsComplete { get; }Whether the operation has finished: succeeded, canceled or failed. Reading it does not count as observing the operation, so a failure it carries is still logged.
Public methods
Action Subscribe(Action onSucceeded = null, Action onCanceledOrDetached = null, Action<Exception> onFailed = null)Registers callbacks that run once, when the operation completes, one per outcome. Any of them may be omitted. Returns an action that unsubscribes them.
void ThrowIfNotSucceeded()Throws if the operation did not succeed. Rethrows the failure a Failed operation carries, with its original stack trace. Throws InvalidOperationException while the operation is running, and OperationCanceledException when it was canceled or detached.
SelvageOperation Detach()Ends the caller's wait now, completing the operation as CanceledOrDetached. The work itself goes on; to stop it, release the context with Manual.Release. Does nothing once the operation is complete, or for one that finished synchronously. Returns this operation, so the call can be chained: await operation.Detach();.
SelvageOperation DetachAfter(TimeSpan timeSpan)
SelvageOperation DetachAfter(float delay)
Ends the caller's wait after a delay, given as a TimeSpan or in seconds, as Detach does. Zero ends it on the next frame; a negative or non-finite delay is ignored. Calling it again replaces the previous delay. Returns this operation.
Task AsTask()Returns a Task that succeeds, fails or is canceled with this operation, for use with Task-based APIs such as Task.WhenAll. It resumes on the main thread. Calling it counts as observing the operation.
TaskAwaiter GetAwaiter()Makes the operation awaitable. Do not call it directly: write await operation;.
Static methods
SelvageOperation Combine(params SelvageOperation[] operations)Combines several operations into one that succeeds when all of them succeed, and takes the first canceled or failed outcome among them. Null entries are ignored, and a detached entry counts as canceled. A failure that arrives after the combined operation completed is not reflected in it, and is logged unless something else observes it. Throws ArgumentNullException when the array is null.
Events
event Action<SelvageOperation> CompletedRaised on the main thread when the operation completes. A handler added after the operation completed is still invoked.

OperationStatus

enum

Outcome of a SelvageOperation.

RunningThe operation has not completed yet.
SucceededThe operation completed successfully.
CanceledOrDetachedThe operation did not complete: the caller ended its wait with Detach or DetachAfter, or the work was canceled.
FailedThe operation completed with a failure, held in Exception.

Channels

ChannelAttribute

attrsealed

Gives a member a channel: a hint for choosing among several dependencies that could be injected into it, such as which of two cameras. A member with only one possible dependency gets it whatever its channel, and a channel nothing matches changes nothing.

ChannelAttribute(object channel)Gives the member channel, any value: a string, an enum value or a number.
object Channel { get; }The member's channel.

DynamicChannelAttribute

attrsealed

Gives a member a channel read from the context when the member is injected, such as a language setting: [DynamicChannel(nameof(language))]. When the value read is null, the member's [Channel] is used, if it has one. The value is read again when the member is reinjected, and not watched in between.

DynamicChannelAttribute(string memberName)Reads the channel from the field or property named memberName, static or not, declared on this class or a base class. Write it with nameof. To use a value from another class, read it through a property of this one. Code analysis reports a name that matches nothing readable (SLV0108); at runtime the member then uses its [Channel], and an error is logged.
string MemberName { get; }The name of the field or property the channel is read from.