Skip to content
Makes things cross-platform
C# Other
  1. C# 99.4%
  2. Other 0.6%
Branch: master
Clone or download
dependabot-preview and glennawatson build(deps): bump Prism.Core from 7.2.0.1367 to 7.2.0.1422 (#432)
Bumps [Prism.Core](https://github.com/PrismLibrary/Prism) from 7.2.0.1367 to 7.2.0.1422.
- [Release notes](https://github.com/PrismLibrary/Prism/releases)
- [Commits](PrismLibrary/Prism@v7.2.0.1367...v7.2.0.1422)

Signed-off-by: dependabot-preview[bot] <support@dependabot.com>
Latest commit 5bd25b2 Nov 22, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Delete release-drafter.yml Aug 5, 2019
script Consolidate build scripts Sep 13, 2018
src build(deps): bump Prism.Core from 7.2.0.1367 to 7.2.0.1422 (#432) Nov 22, 2019
.editorconfig housekeeping: add analyzers similar to ReactiveUI and implement Jan 6, 2019
.gitattributes housekeeping: move to vsts and nerdbank (#191) Jul 24, 2018
.gitignore housekeeping: update the git ignore file. (#375) Aug 5, 2019
CODE_OF_CONDUCT.md housekeeping: update code of conduct to point to single source of truth Sep 11, 2017
CONTRIBUTING.md housekeeping: use reactiveui contributing guidelines as baseline Sep 11, 2017
LICENSE feature: follow ReactiveUI's lead and change to MIT license from MSPL ( May 14, 2018
README.md Update README.md Sep 20, 2019
RELEASENOTES.md
azure-pipelines.yml Update azure-pipelines.yml Aug 5, 2019
build.cake feature: Add Prism DI extensions (#431) Nov 20, 2019
build.cmd housekeeping: add unit tests to splat (#216) Jan 7, 2019
build.config feature: Add Prism DI extensions (#431) Nov 20, 2019
build.ps1 housekeeping: remove redundant code from the build.ps1 Apr 22, 2019
build.sh housekeeping: Update cake scripts to use new recipe/mac suport (#267) Feb 7, 2019
cake.config housekeeping: Added cake.config (#286) Feb 21, 2019
version.json feature: Add Prism DI extensions (#431) Nov 20, 2019

README.md

Splat

NuGet Stats Build Status Code Coverage

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
  • A cross-platform logging framework
  • Simple yet flexible Service Location

How do I install?

Always Be NuGetting. Package contains binaries for:

  • WPF (.NET 4.5)
  • Windows Forms
  • UWP
  • Xamarin (Android, iOS and Mac)
  • .NET Standard 1.0 and 2.0

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 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.

Container NuGet Read Me
Splat.Autofac SplatAutofacBadge Setup Autofac
Splat.DryIoc SplatDryIocBadge Setup DryIoc
Splat.Microsoft.Extensions.DependencyInjection SplatMicrosoftBadge Setup Microsoft DI
Splat.Ninject SplatNinjectBadge Setup Ninject
Splat.SimpleInjector SplatSimpleInjectorBadge

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:

  1. Register an implementation of ILogger using Service Location.
  2. In the class in which you want to log stuff, "implement" the IEnableLogger interface (this is a tag interface, no implementation actually needed).
  3. 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.

Available logging adapters

Splat has support for the following logging frameworks

Target Package NuGet
Console Splat SplatBadge
Debug Splat SplatBadge
Log4Net Splat.Log4Net SplatLog4NetBadge
Microsoft Extensions Logging Splat.Microsoft.Extensions.Logging SplatMicrosoftExtensionsLoggingBadge
NLog Splat.NLog SplatNLogBadge
Serilog Splat.Serilog SplatSerilogBadge

Log4Net

First configure Log4Net. For guidance see https://logging.apache.org/log4net/release/manual/configuration.html

using Splat.Log4Net;

// then in your service locator initialisation
Locator.CurrentMutable.UseLog4NetWithWrappingFullLogger();

Thanks to @dpvreony for first creating this logger.

Microsoft.Extensions.Logging

First configure Microsoft.Extensions.Logging. For guidance see https://docs.microsoft.com/en-us/aspnet/core/fundamentals/logging/

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.

NLog

First configure NLog. For guidance see https://github.com/nlog/nlog/wiki/Tutorial and https://github.com/nlog/nlog/wiki/Configuration-file

using Splat.NLog;

//  then in your service locator initialisation
Locator.CurrentMutable.UseNLogWithWrappingFullLogger();

Thanks to @dpvreony for first creating this logger.

Serilog

First configure Serilog. For guidance see https://github.com/serilog/serilog/wiki/Configuration-Basics

using Splat.Serilog;

// Then in your service locator initialisation
Locator.CurrentMutable.UseSerilogFullLogger()

Thanks to @joelweiss for first creating this logger.

Cross platform drawing

Target Package NuGet
Splat.Drawing Splat.Drawing SplatDrawingBadge

Using Cross-Platform Colors and Geometry

// This System.Drawing class works, even on WinRT or WP8 where it's not supposed to exist
// Also, this works in a Portable Library, in your ViewModel
ProfileBackgroundAccentColor = Color.FromArgb(255, 255, 255, 255);

Later, in the view, we can use it:

ImageView.Background = ViewModel.ProfileBackgroundAccentColor.ToNativeBrush();

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();

Cross-platform Image Loading

You can register with the Splat locators.

Locator.CurrentMutable.RegisterPlatformBitmapLoader();

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();
byte[] imageBytes = await wc.DownloadDataTaskAsync("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(imageBytes, 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();


## Contribute

Splat is developed under an OSI-approved open source license, making it freely usable and distributable, even for commercial use. Because of our Open Collective model for funding and transparency, we are able to funnel support and funds through to our contributors and community. 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:

* [Responding to questions on StackOverflow](https://stackoverflow.com/questions/tagged/splat)
* [Passing on knowledge and teaching the next generation of developers](http://ericsink.com/entries/dont_use_rxui.html)
* [Donations](https://reactiveui.net/donate) and [Corporate Sponsorships](https://reactiveui.net/sponsorship)
* [Asking your employer to reciprocate and contribute to open-source](https://github.com/github/balanced-employee-ip-agreement)
* Submitting documentation updates where you see fit or lacking.
* Making contributions to the code base.
You can’t perform that action at this time.