🚀 Welcome to MDriven Learn –  Don’t miss the latest Release Notes.
HasUserCode - Attribute Side Effects in Turnkey

HasUserCode is a property on an attribute in MDriven Designer. When it is set to True, code generation adds hooks (C# partial methods) to the attribute's getter and setter. You can implement these hooks to run your own code when the attribute is read or changed.

This lets you:

  • change or adjust a value while it is being set,
  • cancel a change,
  • react after a value has changed, or
  • log reads and writes of an attribute.

HasUserCode setting now works in Turnkey when you use CodeDress.

Why HasUserCode is needed

The hooks are partial methods. Code generation only adds them for attributes where HasUserCode is True. This is an optimization: attributes without user code get plain getters and setters with no extra calls.

If you try to implement, for example, Attribute3Changing while HasUserCode is False on Attribute3, the method will not exist and your code will not compile.

Available hooks

With HasUserCode set to True, the generated property looks like this (simplified):

[UmlTaggedValue("Eco.HasUserCode", "True")]
public string Attribute3 {
  get {
    this.Attribute3Reading();
    string res = (string)(/* fetch value */);
    this.Attribute3Read(ref res);
    return res;
  }
  set {
    string oldValue = this.Attribute3;
    string newValue = value;
    bool abortModification = false;
    this.Attribute3Changing(ref value, ref abortModification);
    if (abortModification) {
      return;
    }
    /* store value */
    this.Attribute3Changed(oldValue, newValue, value);
  }
}
Hook When it is called What you can do
<Attr>Reading() Before the value is fetched Run code before a read
<Attr>Read(ref value) After the value is fetched Inspect or change the value returned
<Attr>Changing(ref value, ref abortModification) Before the new value is stored Change the incoming value, or set abortModification = true to cancel
<Attr>Changed(...) After the new value is stored React to the change, using the old and new value

Partial methods are only called if you implement them. Any you leave out cost nothing.

To see the exact signatures for your attribute, look at the generated code for the class (the .eco.cs file) after code generation.

Example

  1. In MDriven Designer, select the attribute (for example Thing.Attribute3) and set HasUserCode to True.
  2. Run Code Generation.
  3. In your partial class file (for example Thing.cs), implement the hooks you need:
namespace Package1
{
  public partial class Thing
  {
    // Adjust the incoming value before it is stored
    partial void Attribute3Changing(ref string value, ref bool abortModification)
    {
      value = value + " (modified by Attribute3Changing)";
    }

    // Log every read of the attribute
    partial void Attribute3Read(ref string value)
    {
      this.SomeString = "Read A3 " + value;
    }
  }
}
  1. Build and upload the model as described in Getting the code into Turnkey. Make a small model change first so the checksum changes and the new code is uploaded.
  2. Make sure the attribute is shown in a view. The Read hook only runs when something actually reads the attribute.

In Turnkey, typing hello into Attribute3 stores hello (modified by Attribute3Changing). Every time the UI reads the value back, SomeString is updated with Read A3 ....

Things to watch out for

  • Read hooks run often. The UI reads values repeatedly, so a side effect in Read or Reading fires many times. This can look strange. These hooks are best for logging, not for changing data.
  • Changing hooks change what the user typed. This is useful for normalizing input, but can surprise users. Use it with care.
  • To react to link changes, use ISingleLinkCatcher. For associations, ISingleLinkCatcher is usually the better option.
  • Whether side effects on attribute changes are good or bad for your app is a design choice. Keep them small and predictable.


​

See also: