LocalStorage is a simple utility that solves a common problem pragmatically - storing and accessing objects quickly in a .NET app. It is designed with a specific vision in mind: provide a simple solution for persisting objects, even between sessions, that is unobtrusive and requires zero configuration.
Note that this library has absolutely nothing to do with Window.localStorage as you know it from web browsers and JavaScript. You cannot, and you arguably should not even want to, read/write data in the Window.localStorage browser space from outside the browser itself.
First, you might want to dive into the examples in this document. Want more, have a look at the tests.
Once you're game, simply add it to your project through NuGet.
NuGet Package Manager:
$ Install-Package LocalStorage
NuGet CLI:
$ nuget install LocalStorage
The LocalStorage library is built on netstandard2.0. This means it's compatible with .NET Core 2.x and up and traditional .NET 4.6.1 and higher. See the Microsoft docs on .NET Standard compatibility.
For traditional .NET 4.6.1+, you also need to have a more recent version of NuGet installed (NuGet v3.6 and up), which comes out-of-the-box with the latest updated versions of Visual Studio 2017 and JetBrains Rider.
... grab a tissue. No, seriously; don't hesitate to post an issue, or send me a message at @jhanssens.
LocalStorage is Copyright © 2016-2017 Juliën Hanssens under the MIT license.
The tests are some pretty good examples to get familiar with the lib. But here is the short summary on the LocalStorage API.
// initialize, with default settings
var storage = new LocalStorage();
// ... or initialize with a custom configuration
var config = new LocalStorageConfiguration() {
// see the section "Configuration" further on
};
var storage = new LocalStorage(config);
// store any object, or collection providing only a 'key'
var key = "whatever";
var value = "...";
storage.Store(key, value);
// fetch any object - as object
storage.Get(key);
// if you know the type, simply provide it as a generic parameter
storage.Get<Animal>(key);
// fetch a strong-typed collection
storage.Query<Animal>(key);
// you can also provide a strong-typed where-clause in one go
storage.Query<Animal>(key, x => x.Name == "Sloth");
Returns the amount of items currently in the LocalStorage container.
Clears the in-memory contents of the LocalStorage, but leaves any persisted state on disk intact.
Deletes the persisted file on disk, if it exists, but keeps the in-memory data intact.
Loads the persisted state from disk into memory, overriding the current memory instance. If the file does not exist, it simply does nothing.
By default, this is done automatically at initialization and can be overriden by disabling AutoLoad
in the configuration.
Persists the in-memory store to disk.
Note that by default, this is also done automatically when the LocalStorage disposes properly. This can be changed by disabling AutoSave
in the configuration.
Here is a sample configuration with all configurable members (and their default values assigned):
AutoLoad (bool)
Indicates if LocalStorage should automatically load previously persisted state from disk, when it is initialized (defaults to true).
AutoSave (bool)
Indicates if LocalStorage should automatically persist the latest state to disk, on dispose (defaults to true).
Filename (string)
Filename for the persisted state on disk (defaults to ".localstorage").
EnableEncryption
Security is an important feature. LocalStorage has support for encrypting the data, both in-memory as well as persisted on disk.
You only need to define a custom configuration indication that encryption should be enabled:
// setup a configuration with encryption enabled (defaults to 'false')
// note that adding EncryptionSalt is optional, but recommended
var config = new LocalStorageConfiguration() {
EnableEncryption = true,
EncryptionSalt = "(optional) add your own random salt string"
};
// initialize LocalStorage with a password of your choice
var encryptedStorage = new LocalStorage(config, "password");
All write operations are first encrypted with AES, before they are persisted in-memory. In case of disk persistance, the encrypted value is respected. Although enabling encryption increases security, it does add a slight overhead to the Get/Store operations, in terms of performance.
By design, only the values are encrypted and not the keys.