Transparent Proxy is a rapid development feature eliminating or reducing the need to author commands and queries. The proxy intercepts method calls, translating them to generic command and query objects (of type ProxyCommand
or ProxyQuery
) which are then dispatched to an IEngine
Transparent proxy is implemented as an extension method of IEngine<T>
. This means proxying can be used with an embedded engine or an OrigoDb client.
The absolute easiest way to create a proxy is using Db.For<MyModel>()
. This will call Engine.For<MyModel>()
and call the GetProxy()
extension method of IEngine<MyModel>
from the OrigoDb.Core.Proxy
namespace:
//create proxy using Db.For
MyModel model = Db.For<MyModel>();
Or you can create it explicitly:
//create proxy explicitly
using OrigoDb.Core.Proxy;
var engine = Engine.For<MyModel>();
MyModel model = engine.GetProxy();
//call a method on the proxy
model.AddReminder("Write more documentation", DateTime.Now.AddDays(1));
Here’s what’s happening under the hood:
ProxyCommand
containing the method name and arguments passed to AddReminderIEngine<T>
instance from which the proxy was createdThe exact same thing happens with queries.
Void public methods are considered commands. Non-void public methods are considered queries. At this time nothing else is proxied. And it won’t work with out, ref or params parameters. So keep it simple!
Sometimes you want to return something from a command method. To avoid it being interpreted as a query, tag it with a Command
attribute:
[Command]
public bool Remove(string key)
{
...
return keyWasRemoved;
}
Warning! If you forget the attribute, nothing gets recorded in the journal, the change is lost and you have an inconsistent model on your hands.
If your command or query returns results that don’t need to be cloned you can set the CloneResult
property on the Command
or Query
attribute:
Keep in mind that query and command results and parameters are cloned. All results and arguments have to be serializable. Design your model as a facade for your domain and keep it simple! The following code will not do as intended because the object returned by GetReminder()
is a clone of the real object.
If you change a method signature on the model, ProxyCommand
objects in the journal could fail.
We are looking at some kind of declarative migrations or an upgrade utility, but for now we recommend not changing any existing command methods.
Also, see the advice on the Schema Evolution page. The reasoning applies also when proxying.