RossWright.MetalInjection.Abstractions 9.0.0-alpha001

Ross Wright's Metal Injection

by Ross Wright

Copyright 2023 Pross Co. All Rights Reserved.

Description

Metal Injection adds property-based service injection, automatic registration of services using attributes or interface inheritance on the service implementation and automatic registration of configuration objects from the app configuration via attributes.

Setup

To setup Metal Injection and auto-register services and configurations on an ASP.NET Core project, add the RossWright.MetalInjection.Server package and call AddMetalInjection on the WebApplicationBuilder in your program.cs file:

var builder = WebApplication.CreateBuilder(args);
builder.AddMetalInjection(_ => _.ScanThisAssembly());

For a Blazor WASM project, add the RossWright.MetalInjection.Blazor package and call AddMetalInjection on the WebAssemblyHostBuilder in your program.cs file:

var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.AddMetalInjection(_ => _.ScanThisAssembly());

Property Injection

To inject a service using property injection, simply preface a public property with the [Inject] attribute. Both InjectAttribute from the Microsoft.AspNetCore.Components and RossWright.MetalInjection namespaces will work.

public class MyServiceThatUsesAnotherService
{
	[Inject] public IAnotherService AnotherService { get; set; } = null!;
}

By using the nullable syntax, you can specify a service is optional and will only be injected if available. For example,

public class MyServiceThatMightUseAnotherService
{
	[Inject] public IAnotherService? AnotherService { get; set; }
}

If an injected service is needed during construction of your class, you need to use constructor injection as property injection happens after the construction of the object.

When an class is created using Microsoft's ActivatorUtilities.CreateInstance property injection is not resolved. In this case, there are several ways to inject services via properties:

1. Add global using ActiatorUtilities = RossWright.MetalInjection.ActivatorUtilities to a file in the project where you are using ActivatorUtilities.CreateInstance and call CreateInstance as normal.
2. Call RossWright.MetalInjection.ActivatorUtilities.CreateInstance explicitly
3. Inject IMetalGrindPropertyInjector and call IMetalGrindPropertyInjector.InjectProperties on the object after creation. Use this when unmodifiable code is calling Microsoft's ActivatorUtilities.CreateInstance and you need to resolve property injection before using the object.

Service Registration via Attribute and Interface

To register a service by decorating the implementation, you can use an attribute:

[Singleton<ISampleService>]
public class SampleService : ISampleService

or an interface:

public class SampleService : ISampleService, ISingleton<ISampleService>

Using the interface syntax has the benefit of providing compile-time checking that a class actually implements/inherits the type it is registered to provide.

Attributes and interfaces are provided for:

• [Singleton] or ISingleton<>
• [ScopedService] or IScopedService<>
• [TransientService] or ITransientService<>.

A single service implementation can be registered for multiple service types, but note for scoped and singleton services only one instance of the implementation will be created per scope or process respectively. For example:

[ScopedService<ISampleService>]
[ScopedService<IAnotherSampleService>]
public class SampleService : ISampleService, IAnotherSampleService

or

public class SampleService : 
	ISampleService, IScopedService<ISampleService>, 
	IAnotherSampleService, IScopedService<IAnotherSampleService>

Configuration Registration

Configuration objects are a great way to access stuctured data from the app configuration (i.e. appsettings.json, environment variables or however you've configured your app configuration). By defining a class that matches the structure of an configuration section, Metal Injection will instantiate, deserialize and register that configuration for easy use by your services. For example, suppose your appsettings.json file contains:

{
	"MyAppSettings": 
	{
		"EmailServerUrl": "https://smtp.mycorp.com",
		"EmailLogin": "EmailSystem",
		"Password": "ERF@$%$!@#F2"
	}
}

In code define a class to bind this section to with a ConfigSection attrbitue:

[ConfigSection("MyAppSettings")]
public class MyAppSettings
{
	public string EmailServerUrl { get; set; } = null!;
	public string EmailLogin { get; set; } = null!;
	public string Password { get; set; } = null!;
}

And then where you need this configuration information, simply inject the configuration:

public class MyEmailService
{
	[Inject] public MyAppSettings Settings { get; set; } = null!;
}

If you'd like to register the config section by a different service type, this can be specified on the attribute:

[ConfigSection<IMyAppSettings>("MyAppSettings")]
public class MyAppSettings : IMyAppSettings

and then,

public class MyEmailService
{
	[Inject] public IMyAppSettings Settings { get; set; } = null!;
}

Licensing

A license must be purchased to use RossWright.Metal libaries in a production environment. For development enviroments, using the libraries without a license will show a console message on initialization and cease functioning after one hour. To install your license file include it in the executable project with the Build Action set to Embedded Resource. The file can be renamed as needed, but must end with the extension .license.