Migrate from Zenject or VContainer
Concepts
Selvage has no container, no installers and no container scopes to declare. The following table lists the Selvage equivalent of each container concept:
| Zenject, VContainer | Selvage |
|---|---|
| Container and installers | The provider list, [Provide] classes, and the registry. |
| Contexts and child scopes | Nothing to declare. What members share per scene, per GameObject or per spawned object follows from where objects are and which members hold them. For more information, refer to Container scopes. |
| Constructor injection | Members only, injected at the end of Awake, OnEnable, or the constructor. |
| Validation when the container builds | Validation in the Dependencies window, without entering Play mode. |
Bindings
| Zenject | VContainer | Selvage |
|---|---|---|
Bind<IFoo>().To<Foo>().AsSingle() | Register<IFoo, Foo>(Lifetime.Singleton) | [Provide] on Foo |
.AsTransient() | Lifetime.Transient | [Provide(Lifetime.Separate)] |
FromInstance(foo) | RegisterInstance(foo) | registry.Add<IFoo>(foo) |
FromMethod(...) | Register<IFoo>(resolver => ...) | registry.Add<IFoo>(() => ...) |
FromComponentSibling(), FromComponentInHierarchy() | RegisterComponentInHierarchy<Foo>() | No code: the Scene Provider |
FromResource(path), FromComponentInNewPrefab(prefab) | RegisterComponentInNewPrefab(prefab) | A Provide Definition |
WithId("main") | A key | A preference or a channel |
In this table, registry stands for RegistryProvider.Listed. Unlike a container singleton,
a Shared instance ends one frame after no member holds it. A Permanent instance stays until play stops (one made in Edit mode, until scripts reload), as a
container singleton does.
Move an installer
The following Zenject installer binds a class to its interface and a camera from the scene. A
SceneContext in the scene runs it:
using Zenject;
public class GameInstaller : MonoInstaller
{
[SerializeField] Camera view;
public override void InstallBindings()
{
Container.Bind<IInventory>().To<Inventory>().AsSingle();
Container.Bind<Camera>().FromInstance(view);
}
}
public class Player : MonoBehaviour
{
[Inject] IInventory inventory;
[Inject] Camera view;
}
The VContainer equivalent is a LifetimeScope in the scene, which also registers the
Player so that VContainer injects it:
using VContainer;
using VContainer.Unity;
public class GameScope : LifetimeScope
{
[SerializeField] Camera view;
protected override void Configure(IContainerBuilder builder)
{
builder.Register<IInventory, Inventory>(Lifetime.Singleton);
builder.RegisterComponent(view);
builder.RegisterComponentInHierarchy<Player>();
}
}
With Selvage, the installer or scope, its GameObject and the camera reference go away. The [Provide]
attribute replaces the binding, and the Scene Provider finds the camera:
using Selvage;
using Selvage.Providers;
[Provide]
public class Inventory : IInventory { ... }
public class Player : MonoBehaviour
{
[Inject] IInventory inventory; // an Inventory, from the Attribute Provider
[Inject] Camera view; // the Camera in the scene, from the Scene Provider
}
The Player class keeps its members. Only its using directive changes.
Container scopes
A container shares objects within the scopes you declare, such as a SceneContext or a child
LifetimeScope. Selvage has no container scopes to declare: an object Selvage creates lives while a member holds
it, and the Scene Provider gives the component closest to the member. The sharing a container scope gives follows
from these rules:
| Zenject, VContainer | Selvage |
|---|---|
Per scene: SceneContext, a scene's LifetimeScope | A component in the scene, which lives with it. A Shared object that only the scene's objects hold ends once the scene unloads, and the next scene's members receive the same object if they need it on the frame it loads. To give one scene its own object of a [Provide] class, add a second preference that sets Scene. |
Per GameObject or prefab instance: GameObjectContext, a child LifetimeScope | A component on the prefab. The Scene Provider looks on the member's GameObject, then its parents and children, so the scripts of each instance receive that instance's own component. To match by hierarchy path instead, use a preference that sets Under. |
| Per spawned object: factory arguments, a sub-container | A local block around new or Instantiate. |
For the whole application: ProjectContext, the root scope | An object with the Permanent lifetime, or an object added to the registry, which Selvage never ends. |
For the reasons behind this model, refer to Lifetimes without container scopes.
Injection
| Zenject, VContainer | Selvage |
|---|---|
[Inject] field or property | [Inject] field or property. |
[Inject] void Construct(...) | Start, or code after Context.WhenReady(this). |
Lazy<T> | The Manual option. |
IInitializable, IStartable | Start, or Context.WhenReady(this). |
| Factories | new and Instantiate. To pass data, use a local block. |
Resolve<T>() | No equivalent: declare a member. For static code, a rare code path or a choice made at runtime, refer to No service locator. |
Container.Inject(obj) | Automatic. For a type from a precompiled DLL, Manual.Inject(obj). |
Run both in one project
During a migration, the Compatibility modules run Selvage beside your container. Each module compiles only when its container is in the project, with nothing to set up:
- The Zenject module requires Zenject or Extenject 9.0 or later. Selvage detects it, including when you imported
it from the Asset Store, and logs a line when it turns the module on or off. Zenject must be in its own assembly:
if it's in
Assembly-CSharp, Selvage reports it with the fix, and the module stays off. - The VContainer module requires the VContainer package 1.17.0 or later.
Give Selvage members what the container has
Add Zenject Provider or VContainer Provider at the bottom of the provider list. The provider asks the container nearest the member's context:
| Context | Zenject | VContainer |
|---|---|---|
| On a GameObject | The GameObjectContext in its parents, else its scene's SceneContext, else the ProjectContext. | The LifetimeScope in its parents, else the first one in its scene, else the root scope. |
| A plain C# class or a ScriptableObject | The ProjectContext. | The root scope. |
To use another container, set ZenjectProvider.Listed.ZenjectContext or VContainerProvider.Listed.Scope
from code. The provider then follows these rules:
- A member's channel is tried first as the binding's identifier or key, then without it.
- A collection member receives every binding of its element type.
- A container that isn't built yet gives nothing, and neither does any container in Edit mode.
- The container owns what it gives: Selvage never ends it.
- The Validation tab shows these members as May Be Supplied, because bindings only exist once installers run.
- When the container throws an exception, the provider logs the container's message, and the member receives nothing from the providers below.
Give the container's classes what Selvage has
For a constructor parameter, an [Inject] method, or code you don't own that expects a binding, bind
the type to Selvage. Each type is bound on its own:
Container.Bind<IAudio>().FromSelvage().AsCached(); // Zenject
builder.RegisterFromSelvage<IAudio>(); // VContainer
builder.RegisterFromSelvage<Camera>(channel: "UI").Keyed("UI");
- With Zenject, the rest of the binding stays Zenject's own. Zenject's scope decides how often Selvage is asked,
and Zenject's default is transient, so add
.AsCached()to ask once. Don't also bindIDisposablefor the type, or Zenject disposes what Selvage owns. - With VContainer, pass the channel when you register, and the lifetime:
Lifetime.Singleton(the default) orLifetime.Transient.Lifetime.Scopedthrows an exception. - When Selvage has nothing for the type, the container throws its own exception, or Zenject gives
nullto an optional injection. - Selvage holds what it gives until the container is disposed. A transient binding to a dependency with the
Separate or Pooled lifetime therefore keeps one object per resolution until then, and
RaiseChangednever reaches what the container received.
Inject each member with one framework
A member is injected by Selvage or by the container, never both. A conflict happens when a Selvage scope, such as
the Inject by Default setting, covers a member that the container's [Inject] marks. After each
compilation, the Console window lists these members with the fix: add [DontInject] to the member, or
[assembly: DontInject] to the assemblies that hold your container code.
When the container injects an object first, such as a component in a scene or a prefab it instantiates, a member
it already filled holds a value, so Selvage leaves it unless the member uses Overwrite.
In a file that uses both frameworks, alias the attribute inside your namespace:
using Inject = Selvage.InjectAttribute;. The same applies to Context with Zenject and to
Lifetime with VContainer.
Migrate step by step
To migrate a project, perform the following steps:
- Add the container's provider at the bottom of the provider list.
- Move each binding to its Selvage equivalent: a
[Provide]class, a registry entry, a scene component, or a Provide Definition. - For code that can't move, such as a package built on the container, bind the types it needs with
FromSelvageorRegisterFromSelvage. - When the Dependencies window shows that the container's provider gives nothing, remove it.