Jot 是一个用于持久化和管理 .NET 应用程序状态的库

Which properties to track

There are two methods (and several overloads) for telling Jot which properties of a given type to track.

The Properties method accepts an expression that projects the target properties as an anonymous object:

tracker.Configure() .Properties(p => new { p.Name, p.LastName, MothersMaidenName = p.Mother.LastName // <-- can navigate object graph })

The Property method is used to add propreties one by one. It allows specifying a name and a default value for each property. Since the property name can be passed as a string, this overload is useful for situations where the properties to track are determined at runtime.

tracker.Configure() .Property(p => p.Name) .Property(p => p.LastName) .Property(p => p.Age, -1) // if there's no value in the store, -1 will be set .Property(p => p.Mother.LastName, "MothersMaidenName") // <-- a name must be provided so it does not colide with p.LastName

The expressions you provide to these methods are used to specify which properties to track. The properties usually belong to the target object itself but they can also navigate through other objects (e.g. p.Mother.LastName). Based on these expressions, Jot will dynamically generate getter and setter methods for reading and writing the data. Both methods (Properties and Property) are cumulative: they add properties to track, rather than overwrite previous calls.

When is the data persisted?

Jot needs to know when a target's data has changed so it can save the updated data to the store. You can tell Jot to automatically persist a target whenever it (the target) fires an event:

tracker.Configure() .Properties(...) .PersistOn(nameof(Foo.SomeEvent)) <-- the event that should trigger persisting

You can optionally specify another object as the source of the event:

PersistOn("SomeEvent", otherObject)

You can also explicitly tell Jot to persist a target using the Persist method:

tracker.Persist(targetObj);

To tell Jot to persist all tracked objects, use the PersistAll method:

tracker.PersistAll();

Usually, this would be during an application shutdown or at the end of a web request. Jot maintains a list of weak references to target objects. Targets that are already garbage collected are ignored.

Some objects survive until the end of the application without being in a usable state. For example, a disposed form can still be referenced (and thus not garbage collected). We do not want to continue tracking that form after it is disposed because it will have bogus property values which we do not want to save to the store. For such cases, we can tell Jot to stop tracking a particular object by calling StopTracking:

tracker.StopTracking(targetObj);

We can also tell Jot to automatically stop tracking an object when it raises a certain event:

tracker.Configure() .Properties(...) .PersistOn(...) .StopTrackingOn(nameof(Form.Closed)) <-- the event that should cause the tracker to stop tracking the target

Where is the data stored?

The Tracker class constructor has an optional parameter that allows you to specify where the data will be stored.

Tracker(IStore store)

Jot comes with a built-in implementation of IStore called jsonFileStore. If the IStore argument is not provided, the data will be stored in json files in the following folder: %AppData%\[company name]\[application name]. The company name and application name are read from the entry assembly's attributes). For each target object, there will be a separate file. Data is stored in separate files in order to make reading and writing data fast.

To keep using the JSON file store, but store the data in a per-machine folder (e.g. CommonApplicationData), configure the tracker like so:

var tracker = new Tracker(new JsonFileStore(Environment.SpecialFolder.CommonApplicationData));

Or specify the storage folder explicitly:

var tracker = new Tracker(new JsonFileStore(@"c:\example\path\"));

Here's what the stored data looks like:

Custom storage

The IStore interface is very simple. For a given Id, it needs to be able to store and retrieve a dictionary of values.

public interface IStore{ void SetData(string id, IDictionary values); IDictionary GetData(string id);}

You can use this interface to make Jot store data anywhere you like e.g. in the cloud (to share settings for a user between machines) or a database.

Value conversions and cancellation

Jot lets you hook into the Apply and Persist operations. You can use this to perform value conversion and cancel persisting or applying data. As we've seen in the WinForms example, we can cancel applying size/location properties for Forms that are maximized or minimized:

tracker.Configure() .Id(...) .Properties(...) .WhenPersistingProperty((f, p) => p.Cancel = (f.WindowState != FormWindowState.Normal && (p.Property == nameof(Form.Height) || p.Property == nameof(Form.Width) || p.Property == nameof(Form.Top) || p.Property == nameof(Form.Left))))

There are four hooks you can use: WhenPersistingProperty, WhenApplyingProperty, WhenAppliedState and WhenPersisted.

Tracking and inheritance

Tracking is configured per-type, meaning that a separate TrackingConfiguration object will need to be defined for each type of object we track. This configuration object tells Jot how to track objects of that type, but it also applies to objects of derived types.

When configuring tracking for a derived type, Jot will examine the inheritance hierarchy of that type and look for the closest ancestor type for which a tracking configuration already exists. If it finds one, it will first create a copy of the base type's tracking configuration which you can then further customize.

For example, let's suppose you define a class called MyForm that derives from Form. In addition to tracking the size and location, you also want to track the selected tab of a TabControl that's part of MyForm. Here's what that might look like:

// configure tracking for Formtracker.Configure() .Id(f => f.Name, SystemInformation.VirtualScreen.Size) .Properties(f => new { f.Height, f.Width, f.Left, f.Top, f.WindowState}) .PersistOn(nameof(Form.Closing)) .StopTrackingOn(nameof(Form.Closed)) .WhenPersistingProperty((f, p) => p.Cancel = (f.WindowState != FormWindowState.Normal && p.Property != nameof(Form.WindowState)))// add the selected tab index for MyForm (everything else is already copied from the configuration for Form)tracker.Configure() .Properties(f => f.tabControl1.SelectedIndex);

We do not have to repeat the tracking configuration for size and location. Since MyForm derives from Form, the configuration for MyForm will be copied from the configuration for Form and we only need to add the additional f.tabControl1.SelectedTabIndex property.

Furthermore, if we configure tracking for Form but not for MyForm, Jot will track MyForm instances using the tracking configuration for Form.

The ITrackingAware interface

Sometimes we cannot know at compile time which properties to track. In those situations, we need to configure tracking on a per-instance basis at runtime. To do this, our tracked objects can implement the ITrackingAware interface.

public interface ITrackingAware{ void ConfigureTracking(TrackingConfiguration configuration);}

In the ConfigureTracking method, the object can dynamically specify which properties to track. The configuration parameter is specific to that instance (and not the type) so each instance can independently adjust its tracking configuration.

For example, let's assume we have a form that has a datagrid, and we want to track the widths of grid columns. We could track each grid column object as a separate object, but we can also track those columns as part of tracking the form. Here's what that might look like:

public class MyFormWithDataGrid : ITrackingAware{ protected override void OnLoad(EventArgs e) { Services.Tracker.Track(this); } public void InitConfiguration(TrackingConfiguration configuration) { // include data grid column widths when tracking this form for (int i = 0; i < dataGridView1.Columns.Count; i++) { var idx = i; // capture i into a variable (cannot use i directly since it changes in each iteration) configuration.Property("grid_c_" + dataGridView1.Columns[idx].Name, f => f.dataGridView1.Columns[idx].Width); } }}

IOC integration

Once we've explained to Jot how to track different types of objects, all that's needed in order for Jot to track instances of those types is to call:

tracker.Track(obj);

Here's the really cool part... When using an IOC container, many objects in the application will be created by the container. This gives us an opportunity to automatically track all created objects by hooking into the container.

For example, with SimpleInjector we can do this quite easily, with a single line of code:

var tracker = new Jot.Tracker();var container = new SimpleInjector.Container();//configure tracking and apply previously stored data to all created objectscontainer.RegisterInitializer(d => { tracker.Track(d.Instance); }, cx => true);

With this in place, we can easily make any property of any object persistent, just by modifying the tracking configuration for its type. Neat!

Demos

Demo projects for WPF and WinForms are included in the repository.

Contributing

You can contribute to this project in the usual way:

First of all, don't forget to star the projectFork the projectPush your commits to your forkMake a pull request

TODO

Async supportIOC demosaspnet core (demo + readme section)

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。