Certain types of things are basically impossible to do in cross-platform
mobile code today, yet there's no reason why. Writing a ViewModel that handles
loading a gallery of pictures from disk will be completely riddled with
#ifdefs and basically unreadable.
Splat aims to fix that, by providing a usable leaky abstraction above platform
code. It is leaky, because it always provides an extension method ToNative()
and FromNative(), which converts the abstraction to the platform-specific
version. Load the image in the cross-platform code, then call ToNative() in
your view to actually display it.
What does it do?
Splat currently supports:
Cross-platform image loading/saving
A port of System.Drawing.Color for portable libraries
Cross-platform geometry primitives (PointF, SizeF, RectangleF), as well as a bunch of
additional extension methods to make using them easier.
A way to detect whether you're in a Unit Test runner / Design Mode
.NET Framework 4.6.2, .NET Framework 4.7.2, .NET Standard 2.0, .NET 6.0, and .NET 8.0
Works with:
WPF
Windows Forms
WinUI 3
Maui (WinUI, Android, iOS and Mac)
Avalonia
Detecting whether you're in a unit test runner
// If true, we are running unit tests
ModeDetector.InUnitTestRunner();
Service Location
Splat provides a simple service location implementation that is optimized for
Desktop and Mobile applications, while still remaining reasonably flexible.
There are 2 parts to the locator design:
Locator.Current The property to use to retrieve services. Locator.Current is a static variable that can be set on startup, to adapt Splat to other DI/IoC frameworks. We're currently working from v7 onward to make it easier to use your DI/IoC framework of choice. (see below)
Locator.CurrentMutable The property to use to register services
To get a service:
// To get a single service registration
var toaster = Locator.Current.GetService<IToaster>();
// To get all service registrations
var allToasterImpls = Locator.Current.GetServices<IToaster>();
Locator.Current is a static variable that can be set on startup, to adapt Splat
to other DI/IoC frameworks. We're currently working from v7 onward to make it easier to use your DI/IoC framework of choice.
The default implementation of Service Location also allows new types to be
registered at runtime.
// Create a new Toaster any time someone asks
Locator.CurrentMutable.Register(() => new Toaster(), typeof(IToaster));
// Register a singleton instance
Locator.CurrentMutable.RegisterConstant(new ExtraGoodToaster(), typeof(IToaster));
// Register a singleton which won't get created until the first user accesses it
Locator.CurrentMutable.RegisterLazySingleton(() => new LazyToaster(), typeof(IToaster));
Dependency Injection Source Generator
There is a source generator that will inject constructor and properties. See here for instructions.
Dependency Resolver Packages
For each of the provided dependency resolver adapters, there is a specific package that allows the service locator to be implemented by another ioc container.
Note: When using ReactiveUI and overriding Splat's default behavior, you have to be sure to initialize ReactiveUI before your container finalizes.
Please note: If you are adjusting behaviours of Splat by working with your custom container directly. Please read the relevant projects documentation on
REPLACING the registration. If the container supports appending\ multiple registrations you may get undesired behaviours, such as the wrong logger factory
being used.
AppBuilder and IModule (AOT-friendly configuration)
When targeting AOT or trimming scenarios, you can configure Splat (and consumers such as ReactiveUI) without reflection using the AppBuilder and IModule pattern.
IModule defines a single Configure(IMutableDependencyResolver) method where you register services.
AppBuilder gathers modules and custom registrations, then applies them to a chosen resolver when Build() is called.
You can target the current Locator.CurrentMutable or an external container that implements IMutableDependencyResolver via UseCurrentSplatLocator().
Define modules
using Splat;
using Splat.Builder;
// App services
public sealed class CoreModule : IModule
{
public void Configure(IMutableDependencyResolver resolver)
{
// register your services here
resolver.RegisterLazySingleton(() => new ApiClient(), typeof(IApiClient));
resolver.Register(() => new MainViewModel(resolver.GetService<IApiClient>()!), typeof(IMainViewModel));
}
}
// Logging (Serilog adapter) - requires Splat.Serilog package
using Splat.Serilog;
public sealed class SerilogModule : IModule
{
public void Configure(IMutableDependencyResolver resolver)
{
// assumes Serilog.Log has been configured elsewhere
resolver.UseSerilogFullLogger();
}
}
// Cross-platform drawing (IBitmapLoader) - requires Splat.Drawing package
public sealed class DrawingModule : IModule
{
public void Configure(IMutableDependencyResolver resolver)
{
resolver.RegisterPlatformBitmapLoader();
}
}
Tip: You can also apply a module immediately to the current locator without a builder:
new CoreModule().Apply(); // calls module.Configure(Locator.CurrentMutable)
Build your application registrations
using Splat;
using Splat.Builder;
// choose the resolver to configure (Locator.CurrentMutable by default)
new AppBuilder(Locator.CurrentMutable)
.UsingModule(new CoreModule())
.UsingModule(new SerilogModule())
.UsingModule(new DrawingModule())
// ad-hoc registrations can be added too
.WithCustomRegistration(r => r.RegisterConstant(new AppConfig("Prod"), typeof(AppConfig)))
.Build();
Using an external container as the Splat resolver
If you adapt an external container to Splat first, UseCurrentSplatLocator() ensures later module registrations are applied to that container instance.
Microsoft.Extensions.DependencyInjection example:
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Splat;
using Splat.Builder;
using Splat.Microsoft.Extensions.DependencyInjection;
using Splat.Microsoft.Extensions.Logging;
var services = new ServiceCollection();
services.UseMicrosoftDependencyResolver(); // set Locator.Current to MS.DI resolver backed by IServiceCollection
// register framework logging provider that forwards to Splat
services.AddLogging(b => b.AddSplat());
// build container and rebind Locator.Current to the built provider
var provider = services.BuildServiceProvider();
provider.UseMicrosoftDependencyResolver();
new AppBuilder(Locator.CurrentMutable)
.UseCurrentSplatLocator() // target whatever Locator.CurrentMutable points to (MS.DI in this case)
.UsingModule(new CoreModule())
.WithCustomRegistration(r =>
{
// forward Microsoft.Extensions.Logging to Splat
var factory = provider.GetRequiredService<ILoggerFactory>();
r.UseMicrosoftExtensionsLoggingWithWrappingFullLogger(factory);
})
.Build();
The same pattern works with other adapters (Autofac, DryIoc, SimpleInjector, Ninject) after setting Locator.Current to the adapter’s resolver.
Extending AppBuilder
AppBuilder is extensible. Override WithCoreServices() to ensure common registrations are always applied before modules:
using Splat;
using Splat.Builder;
public sealed class MyAppBuilder : AppBuilder
{
public MyAppBuilder(IMutableDependencyResolver resolver) : base(resolver) { }
public override AppBuilder WithCoreServices()
{
// register core bits once for your app
// e.g., default logger, scheduler, or platform services
// resolver is obtained per registration in Build(),
// so prefer idempotent registrations guarded by HasRegistration
return this;
}
}
// usage
new MyAppBuilder(Locator.CurrentMutable)
.UsingModule(new CoreModule())
.Build();
Notes:
Build() is idempotent per process: subsequent calls no-op after the first successful build.
Prefer RegisterLazySingleton for singletons and check HasRegistration when composing multiple modules.
Logging
Splat provides a simple logging proxy for libraries and applications to set up.
By default, this logging isn't configured (i.e. it logs to the Null Logger). To
set up logging:
Register an implementation of ILogger using Service Location.
In the class in which you want to log stuff, "implement" the IEnableLogger
interface (this is a tag interface, no implementation actually needed).
Call the Log method to write log entries:
this.Log().Warn("Something bad happened: {0}", errorMessage);
this.Log().ErrorException("Tried to do a thing and failed", exception);
For static methods, LogHost.Default can be used as the object to write a log
entry for. The Static logger uses a different interface from the main logger to allow capture of additional
caller context as it doesn't have the details of the class instance etc. when compared to the normal logger.
To get the benefit of these you don't need to do much as they are optional parameters at the end of the methods
that are utilised by the compiler\framework. Currently we only capture CallerMemberName.
Available logging adapters
Splat has support for the following logging frameworks
using Splat.Microsoft.Extensions.Logging;
// note: this is different from the other adapter extension methods
// as it needs knowledge of the logger factory
// also the "container" is how you configured the Microsoft.Logging.Extensions
var loggerFactory = container.Resolve<ILoggerFactory>();
// in theory it could also be
// var loggerFactory = new LoggerFactory();
/// then in your service locator initialisation
Locator.CurrentMutable.UseMicrosoftExtensionsLoggingWithWrappingFullLogger(loggerFactory);
Thanks to @dpvreony for first creating this logger.
// This System.Drawing class works, even on WinRT where it's not supposed to exist
// Also, this works in a Portable Library, in your ViewModel
ProfileBackgroundAccentColor = Color.FromArgb(255, 255, 255, 255);
If targeting iOS or Mac in a cross-platform solution (e.g. iOS & Android), use
the SplatColor class to define colors in your netstandard library
(since Cocoa doesn't include System.Drawing.Color).
// In a netstandard library
SplatColor BackgroundColor = SplatColor.Red;
// From an iOS project
UIColor bgColor = ViewModel.BackgroundColor.ToNative();
// From an Android project
Android.Graphics.Color bgColor = ViewModel.BackgroundColor.ToNative();
You can then load your images in a cross platform way:
//
// Load an Image
// This code even works in a Portable Library
//
var wc = new WebClient();
Stream imageStream = wc.OpenRead("http://octodex.github.com/images/Professortocat_v2.png");
// IBitmap is a type that provides basic image information such as dimensions
IBitmap profileImage = await BitmapLoader.Current.Load(imageStream, null /* Use original width */, null /* Use original height */);
Then later, in your View:
// ToNative always converts an IBitmap into the type that the platform
// uses, such as UIBitmap on iOS or BitmapSource in WPF
ImageView.Source = ViewModel.ProfileImage.ToNative();
Images can also be loaded from a Resource. On Android, this can either be a
Resource ID casted to a string, or the name of the resource as as string
(optionally including the extension).
var profileImage = await BitmapLoader.Current.LoadFromResource("DefaultAvatar.png", null, null);
Bitmaps can also be created and saved - actually drawing on the image is
beyond the scope of this library, you should do this in your view-specific
code.
var blankImage = BitmapLoader.Current.Create(512.0f, 512.0f);
await blankImage.Save(CompressedBitmapFormat.Png, 0.0, File.Open("ItsBlank.png"));
Detecting if you're in design mode
// If true, we are running inside Blend, so don't do anything
PlatformModeDetector.InDesignMode();
Application Performance Monitoring
Application Performance Monitoring is split into the follow sections
Error Reporting
Feature Usage Tracking
View Tracking
The table below shows the support across various APM packages
To sit on top of existing APM libaries using native features where possible, or by using a common convention that gives parity in behaviour.
** Where there is a convention behaviour it will be detailed under the relevant frameworks documentation.
To define basic behaviours that are dropped into consuming libraries, for example with ReactiveUI
** Commands
** ViewModels
** Views
Getting started with APM with Splat
Splat comes with a default implementation that pushes events into your active Splat logging framework. This allows for design and testing prior to hooking up a full APM offering.
Error Reporting
TODO
Feature Usage Tracking
The most basic ability for feature usage tracking is to implement the Splat.ApplicationPerformanceMonitoring.IEnableFeatureUsageTracking interface. This has the same behaviour as the logging interface and allows Splat to inject whichever
APM platform is registered with the ServiceLocator at initialization.
/// <summary>
/// Dummy object for testing IEnableFeatureUsageTracking.
/// </summary>
public sealed class TestObjectThatSupportsFeatureUsageTracking : IEnableFeatureUsageTracking
{
public async Task SomeFeatureIWantToTrack()
{
using (var trackingSession = this.FeatureUsageTrackingSession("featureName"))
{
try
{
// do some work here.
}
catch (Exception exception)
{
trackingSession.OnException(exception);
}
}
}
}
Splat also has the notion of subfeatures, some APM platforms support this natively, others have been done by convention, which will be explained in the relevant library.
Splat itself does not dictate when these should be used. It's up to you. You may have a primary feature (such as a search view) and then track buttons, etc. on that view
as subfeatures.
/// <summary>
/// Dummy object for testing IEnableFeatureUsageTracking.
/// </summary>
public sealed class TestObjectThatSupportsFeatureUsageTracking : IEnableFeatureUsageTracking
{
public async Task SomeFeatureIWantToTrack()
{
using (var mainFeature = this.FeatureUsageTrackingSession("featureName"))
{
try
{
await DoSubFeature(mainFeature).ConfigureAwait(false);
}
catch (Exception exception)
{
mainFeature.OnException(exception);
}
}
}
public async Task SomeFeatureIWantToTrack(IFeatureUsageTrackingSession parentFeature)
{
using (var subFeature = parentFeature.SubFeature("subFeatureName"))
{
try
{
// do some work here.
}
catch (Exception exception)
{
subFeature.OnException(exception);
}
}
}
}
using Splat.Exceptionless;
// then in your service locator initialisation
Locator.CurrentMutable.UseExceptionlessApm();
Configuring New Relic
New Relic support isn't currently available.
Configuring OpenTrace
OpenTrace support isn't currently available.
Configuring Raygun
First configure Raygun. For guidance see TODO
using Splat.Raygun;
// then in your service locator initialisation
Locator.CurrentMutable.UseRaygunApm();
Testing and developing the APM functionality
The unit tests for this functionality do not generate activity to the relevant platform.
The integration tests DO SEND TEST DATA to the relevant platforms, so they need to have
the user-secrets configured. There is a script in the \scripts\inttestusersecrets.cmd
that shows how to set the relevant secrets up.
Contribute
Splat is developed under an OSI-approved open source license, making it freely usable and distributable, even for commercial use. We ❤ the people who are involved in this project, and we’d love to have you on board, especially if you are just getting started or have never contributed to open-source before.
So here's to you, lovely person who wants to join us — this is how you can support us:
<br>
<a href="https://www.nuget.org/packages/splat">
<img src="https://img.shields.io/nuget/dt/splat.svg">
</a>
<a href="https://reactiveui.net/slack">
<img src="https://img.shields.io/badge/chat-slack-blue.svg">
</a>
