ExtendingWriting your own provider.
Writing a provider
Base class for every provider: an object that supplies dependencies to members. When a member needs a dependency, Selvage tries the providers one by one, in the order of the provider list (Project Settings > Selvage, plus any added from code with Injector), and the first one that supplies something wins.
To write one, derive from this class and mark it [Serializable] so it can be added to the provider list. Override Evaluate, and override either Provide, when every dependency is ready at once, or ProvideAsync, when getting one can take time. Everything else is optional. The provider's serialized fields are its settings, edited on its row in the provider list. Selvage calls every method on the Unity main thread.
Properties
| bool Enabled { get; set; } | Whether the provider is tried. Set it to false from code to skip the provider as if it were not in the list. It is not saved: every listed provider is enabled when the settings load, and exiting Play mode puts every provider back as it was before Play mode. Changing it calls Reevaluate(). The provider list shows a disabled provider dimmed, its summary reading Off. |
Protected methods
Override exactly one of
Provide and
ProvideAsync, and at most one of
TearDown and
TearDownAsync. Code analysis reports any other combination as an error (
SLV0004), and adding such a provider throws ArgumentException.
| abstract Verdict Evaluate(Request request) | Override this method to say what the provider does for a request: never supplies it, may or always supplies it, vetoes it, or redirects it to the provider list (see Verdict). Selvage evaluates once per member and remembers the verdict, so base it only on the request and the provider's settings. The Editor also reads it, to show which provider supplies each member and whether every required member is guaranteed a dependency. |
| virtual object ShareKey(Request request, object context, object channel) | Override this method to share one instance between every request that gives the same key. A fixed key such as typeof(IInventory) makes a single shared instance; the GameObject of context makes one per GameObject. While an instance for the key exists, it is reused without calling Provide. The same context and channel must always give the same key. Returns null by default, which answers each request on its own. Called for every request: a reference-type key allocates nothing, a value-type key (a tuple, a Scene) is boxed each time. |
| virtual Supply Provide(Request request, object context, object channel) | Override this method to return the dependency for a request the provider evaluated Maybe or Always (see Supply). context is the object being injected, or the class's Type for a static member. channel is the member's channel at this injection (its [DynamicChannel] value, else its [Channel], else null), a hint the provider may ignore. Return Supply.Decline() when the provider has nothing, and the next provider is tried; declining after Always breaks the verdict and is logged as an error. Throwing is not a decline: the member fails with the exception, and no later provider is tried. |
| virtual ValueTask<Supply> ProvideAsync(Request request, object context, object channel, CancellationToken cancellationToken) | Override this method instead of Provide when getting a dependency can take time, such as loading a file or an Addressables asset. Write it with async/await, and complete with Supply.Decline() when the provider has nothing. cancellationToken is canceled once no member waits for the result any more, or when you exit Play mode; a result that still completes is torn down. For a verdict without mustWait, the answer must be ready at once, and every member gets it; finishing later is an error that names the provider. For a verdict with mustWait, only Async members wait for it, a Warm member has it prepared and receives it once it is ready when it is also Reactive, else on its next Manual.Reinject, and any other member uses the provider only for a shared instance that already exists; the Editor flags such a member when no other provider can supply it. An answer ready at once completes without waiting a frame, and allocates nothing. |
| virtual void TearDown(object instance) | Override this method to run your own teardown on an instance the provider supplied, borrowed or owned, once the last member holding it released it: return it to a pool, release an Addressables asset, destroy a prefab's whole GameObject. Does nothing by default. Selvage then ends an instance supplied with Supply.Owned the standard way, which cannot be skipped; supply it with Supply.Made when your teardown is the whole ending. |
| virtual ValueTask TearDownAsync(object instance) | Override this method instead of TearDown when tearing down has to wait for something, such as saving to a file. It is called in the same cases, under the same rules. Selvage waits for it before ending an owned instance, and before tearing down the next member's dependency. |
| void RaiseChanged(bool revoked = false) | Call it when what the provider supplies may have changed, such as when a newer version of everything it supplied exists. Every Reactive member holding something it supplied is injected again from the whole provider list, a Reactive member holding nothing is injected again, and any other member keeps the one it has. The remembered verdicts stay: after a change to what Evaluate answers, call Reevaluate. Pass revoked: true when nothing it supplied may be used any more: every Reactive member holding one drops it on the next frame and receives a replacement when one exists, and so does every other member holding one supplied with canRevoke: true (on the verdict or the supply), which returns to its default. A revoke that reaches no member logs a warning. |
| bool RaiseChanged(object dependency, bool revoked = false) | Call it when one dependency the provider supplied has a newer version. Only the members holding it from this provider are reached: a Reactive one is injected again from the whole provider list, and any other keeps the one it has. Pass revoked: true when it must not be used any more, such as a closed connection: every Reactive member holding it drops it on the next frame and receives a replacement when one exists, and so does every other member when it was supplied with canRevoke: true, which returns to its default. A revoke that reaches no member logs a warning. Returns whether members hold the dependency from this provider: false when no member holds it, or members hold it from another provider. Throws ArgumentNullException when the dependency is null. |
| void Reevaluate() | Call it after changing something Evaluate reads, such as one of the provider's settings. Selvage forgets the verdicts it remembered from this provider and asks again for every member, then reaches the members as RaiseChanged() does. Editing the provider's settings in Project Settings and changing Enabled call it. |
Protected static methods
| T InList<T>() | Returns the first provider of exactly class T in the provider list, enabled or not, or null when the list has none. Use it to reach a provider whose class is marked [OnePerList]: public static SaveProvider Listed => InList<SaveProvider>();. |
What a provider does for a request, returned by Provider.Evaluate.
Supplying
| static Verdict Never | The provider never supplies the request: it is skipped, and the next provider is tried. |
| static Verdict Maybe(bool canRevoke = false, bool mustWait = false, Type makes = null) | The provider is asked through Provide, and may supply or decline: whether it has something is known only when the member is injected, as with registrations made in code. canRevoke, mustWait and makes mean the same as for Always. |
| static Verdict Always(bool canRevoke = false, bool mustWait = false, Type makes = null) | The provider is asked through Provide, and always supplies: a member that reaches it is guaranteed a dependency. A decline after this verdict is logged as an error, and the next provider is tried. canRevoke lets a revoke reach every member holding what was supplied for this request, not only Reactive ones, for a dependency that may have to be dropped while held, such as a closed connection; to mark one supplied object instead, pass it to Supply. mustWait gives the answer only to members that can wait for it: Async members wait, a Warm member has it prepared and receives it once it is ready when it is also Reactive, else on its next Manual.Reinject, and every other member skips the provider. Set it when ProvideAsync may take time for this request, such as loading an Addressables asset; without it, the answer must be ready at once. makes is the class the provider creates for the request, when it is known before you enter Play mode, so the Inspector window and the Dependencies window can report a dependency cycle through it; leave it null when the provider supplies objects it doesn't create. A class the request can't hold is ignored, with an error. |
Vetoing
| static Verdict Veto(string reason = null) | Nothing may supply the request, and no later provider is tried: the member stays missing. Use it to forbid something a provider further down would otherwise supply. The Inspector window and the Dependencies window show reason, and so does the error a required member fails with. |
Redirecting
| static Verdict Redirect(Type type) | Answers with whatever the provider list supplies for type, which must be assignable to the requested type: for example, a request for IInventory redirected to Inventory. A type that is not assignable is logged as an error, and the member stays missing. Throws ArgumentNullException when type is null. |
What Provider.Provide or Provider.ProvideAsync returns: the dependency and whether Selvage ends it, or a decline or a veto.
Supplying
| static Supply Borrowed(object instance, bool canRevoke = false) | Supplies an instance Selvage never ends, because something else is responsible for it: a component in the scene, or the provider itself through its TearDown (an Addressables asset). Selvage doesn't inject it: for an instance the provider has just made, use Made. canRevoke lets a revoke of this object (RaiseChanged(instance, revoked: true)) reach every member holding it, not only Reactive ones; for every object of a request, pass it to the verdict instead. Throws ArgumentNullException when the instance is null or a destroyed Unity object. |
| static Supply Owned(object instance, bool canRevoke = false) | Supplies an instance Selvage ends once no member uses it, after the provider's TearDown: a UnityEngine.Object is destroyed (the object itself and nothing more), anything else is disposed if it is IDisposable or IAsyncDisposable. canRevoke is as for Borrowed. Throws ArgumentNullException when the instance is null or a destroyed Unity object. |
| static Supply Made(object instance, bool canRevoke = false) | Supplies an instance the provider has just made, or taken from a pool of its own, and ends itself in TearDown: Selvage injects it each time it is supplied, and never ends it. Use it for a pooled object, or an instance whose ending is more than the standard one, such as a component whose whole GameObject has to go. canRevoke is as for Borrowed. Throws ArgumentNullException when the instance is null or a destroyed Unity object. |
Declining or vetoing
| static Supply Decline(string reason = null) | The provider has nothing for the request: the next provider in the list is tried. The error logged when the decline breaks an Always verdict gives reason. |
| static Supply Veto(string reason) | The provider can't supply the request, and no later provider may: the member stays missing, and reason is logged as an error. Use it when what decides is known only at injection, such as several candidates nothing tells apart; a veto known before you enter Play mode is Verdict.Veto. Throws ArgumentNullException when reason is null or empty. |
What a member asks for: the type it wants and where it is declared. It never holds the object being injected, which Provide receives separately as context.
Properties
| Type Type { get; } | The type asked for: the member's own type, or the type a Verdict.Redirect names. |
| Type ContextType { get; } | The type of the object being injected. |
| MemberInfo Member { get; } | The field or property being injected, for example to read an attribute on it, or null when no member is behind the request. |
| Type ElementType { get; } | The type of the elements when Type is an array or an IEnumerable<T>, otherwise null. |
| object FixedChannel { get; } | The member's channel when it is known before you enter Play mode: its [Channel], when it has no [DynamicChannel]. Null otherwise. A hint Evaluate may use or ignore; ShareKey and Provide receive the channel at injection. |
Utility
Limits the provider list in Project Settings > Selvage to one provider of the marked class: [Serializable, OnePerList] public sealed class SaveProvider : Provider. Each class deriving from a marked class counts on its own. Providers added from code with Injector are not limited. While one is listed, the + menu disables the class; a second one arriving through a setup or a merge is removed with an error, and the first keeps its place. The listed provider stays the same object until scripts are reloaded, even when it is removed and added again, so what code gave it survives editing the list. Reach it with Provider.InList.