OwofGames.GodotHost 0.1.3

Godot Host

This project provides a service similar to that of Microsoft's generic host, and offers the following features with sensible defaults and the possibility to customize them as necessary:

• Dependency Injection (DI)
• Configuration
• Logging

Quickstart

Add OwofGames.GodotHost to the project via NuGet. Then, in any initialization script:

var host = new HostBuilder().Build();

Now you can expose and use the host variable to access the various features:

var myInstance = host.ServiceProvider.GetRequiredService<IMyInterface>();
var configuration = host.Configuration.GetSection("MyConfiguration").Get<MyConfiguration>();
var logger = host.GetLogger<Initialization>();

Host and Host Builder

A host is a collection of services and facilities. A host is always created by a Host Builder.

The host builder has a number of sensible defaults for Godot. They can all be overriden by the various methods of the host builder through a fluent interface. Once the customizations are performed, the host builder's method Build is called to finalize the creation of a Host (from that moment on, the Host Builder can no longer build other hosts).

What follows are the details of the services provided by the Host and how they can be personalized through the Host Builder.

Dependency injection

Dependency injection is based on Microsoft.Extensions.DependencyInject.

The host provides a number of services already available once the initialization is completed:

• IConfiguration
• All the options-related ones (IOptions<>, IOptionsSnapshot<>, etc...)
• ILoggerFactory and ILogger<>
• IHostBuilderParameters (summary of all the parameters used to build the host)

These services can be extended (or replaced!) by hooking into .SetServiceCollectionBuilder(callback)'s builder method.

Microsoft's default DI engine can be replaced by calling .SetServiceProviderFactory with an alternative service provider factory (AutoFac, DryIoc, ecc...).

When in editor mode, the default DI engine is also set to perform checks regarding the registrations (ValidateScopes and ValidateOnBuild). This behavior can be overridden by calling .SetServiceProviderFactory(new DefaultServiceProviderFactory()) on the host builder.

Configuration

The configuration is based on the Microsoft.Extensions.Configuration package.

The configurations are read by default from the following sources (starting from the highest priority):

• Command line
• Environment variables
• In the filesystem rooted at the current working directory:
  • The file appsettings.environment-name.json (environment-name is either editor or production)
  • The file appsettings.json
• In the res:// filesystem:
  • The same files as above
• A base configuration builder

Configurations are expressed in a hierarchical way: there is a root configuration which contains various couples key-value, and then it can contain named sections which on their own contain couple key-values, which can contains subsections, and so on. This kind of structure can be thought of as a JSON file.

Most of the time, configurations or configuration sections are then bound to C# objects, which allow for all kinds of automatic conversions to happen, and optionally hooked into the options system to get notified of changes.

Command line

The command line parser is the one provided by Microsoft through the Microsoft.Extensions.Configuration.CommandLine package.

Arguments from the command line are expressed in the following format:

• An optional prefix, which can be -- (double dash), - (single dash - only valid with Switch mappings, see below) or / (forward slash);
• The key of the property;
• An = (equal) sign, which is optional is the prefix is present, and required if the prefix is absent;
• If the optional = is present, the value of the property is the string following the =, otherwise the value is the next argument

E.g.:

• --Logging:LogLevel:Default=Warning
• /Logging:LogLevel:Default Warning
• Logging:LogLevel:Default=Warning
• Logging:LogLevel:Default Warning ⇐ not valid, without a prefix the = is required

As one can see from the example, the key contains the full path of sections to reach the actual key to change, splitting them with a : separator.

Switch mappings

Since some options can be particularly long (see the Logging:LogLevel:Default example above), it's possible to provide switch mappings. These are an extra dictionary passed that maps arguments (including their prefix) to argument names (without prefix). E.g.:

new Dictionary<string, string> {
    { "--default-log-level", "Logging:LogLevel:Default" }
}

This makes it possible to use an option like --default-log-level=Warning.

Note that the above example won't enable the option /default-log-level=Warning.

The - (single dash) prefix is available only when used as a switch mapping.

All keys in switch mapping are case-insensitive.

Environment variables

The environment variables parser is the one provided by Microsoft.

Environment variables that start with the GODOT_HOST_ prefix are stripped of this prefix, then __ (double underscore) are transformed into :, and finally their value interpreted as configuration. The interpretation is similar to that of the command line variables.

For example, this environment variable could be used to override the minimum log level:

GODOT_HOST_LOGGING__LOGLEVEL__DEFAULT=Error ./my_game

File sources

The host builder uses a composite strategy by default to find files:

• at first, it looks for the configuration file in the filesystem, rooted at the current working directory
• if it's not found, it's searched for in the res:// filesystem

While working in the editor, the two strategies provide the same files. When running in an exported project, though, the configuration file will be only present in the res:// filesystem, and they can be overridden by manually adding configuration files next to the binary of the game.

Usually, one needs only to set up appsettings.json, but if you need specific changes according to the environment there's also appsettings.<environment-name>.json, so you can have an appsettings.editor.json and/o appsettings.production.json.

Base configuration

The default behavior of the host is to create a new ConfigurationManager instance to handle the various layers of configurations to read. It's also possible to provide a starting IConfigurationBuilder to create the configuration on top of. This allows to preload come configuration in it, which serve as a basic configuration layer.

E.g.:

var configurationManager = new ConfigurationManager();
configurationManager.AddInMemoryCollection(new Dictionary<string, string>
{
    { "Logging:LogLevel:Default", "Warning" }
}!);
var logger = new HostBuilder()
    // ...
    .SetConfigurationBuilder(configurationManager)
    // ...
    .Build();

Automatic reload

The Godot Host is configured to automatically reload configuration from files when they change.

This behavior can be disabled by calling .SetReloadOnChange(false) on the builder.

Logging

The logging system is based on owof games' GodotLogger.

The standard machinery for logging is deployed, which means that the configuration file(s) can control the logging filtering like in ASP.NET.

GodotLogger's provider name is "Godot", and inside the provider configuration the following properties are available ( see also all the public properties of GodotLoggerConfiguration):

• "GodotLoggerMessageFormatterString": The format string for the messages.
• "TraceColor",
• "DebugColor",
• "InformationColor",
• "WarningColor",
• "ErrorColor": The color names for the various log levels.
• "IsTraceBold",
• "IsDebugBold",
• "IsInformationBold",
• "IsWarningBold",
• "IsErrorBold": Whether each level is bold or not.
• "IsTraceItalic",
• "IsDebugItalic",
• "IsInformationItalic",
• "IsWarningItalic",
• "IsErrorItalic": Whether each level is italic or not.

E.g.:

{
  "Logging": {
    "Godot": {
      "WarningColor": "Orange",
      "MessageFormat": "{EventId} - {Category,10} - {LogLevel,15:G} - {Timestamp:dd/MM/yyyy} - {Message}",
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}