Sometimes you want to use custom entity instead of using prepared one. The typical reasons are:

• Original entity is large - you want to use just subset of fields.
• There is not provided entity in core library (finaly you can share your entity with others :-) )

For basic ideas about entities see this wiki page. On this tutorial I will try to explain details about O/R mapper logic. If you want to test pure API commands to be sure about protocol, see notice about console project

Main logic

Mapper scans entity for its attributes and than performs operations. The only two things that are important are:

• attributes
• property types

Attributes

TikEntity

Attribute that is used to decorate tik entity class. Every entity class have to be decorated by this attribute to enable O/R mapper logic.

• EntityPath: The entity path in API notation (/ip/firewall/mangle).
• IsReadOnly: If the whole entity is R/O.
• IsOrdered: If entity list is ordered (move operation does make sense)
• IncludeDetails: If entity should be loaded with =detail= option.
• IncludeProplist: If entity fields should be listed explicitly via .proplist option.
• IsSingleton: If entity exists in single instance. (for example /system/resource)

[TikEntity("/log", IsReadOnly = true)]
public class Log

TikProperty

Attribute to mark object property as readable/writable from/to mikrotik router. Every entity property have to be decorated by this attribute to enable O/R mapper logic.

• FieldName: Gets the name of the property (on mikrotik).
• IsMandatory: Gets a value indicating whether this property is mandatory - should be always present in loaded resultset.
• IsReadOnly: If the property is R/O (should not be updated during save modified entity).
• DefaultValue: Property default value (if is different from type default).
• UnsetOnDefault: If unset command should be called when saving modified object and marked property contains DefaultValue or null (set to default value will be used when false).

    [TikEntity("/log", IsReadOnly = true)]
    public class Log
    {
        [TikProperty(".id", IsReadOnly = true, IsMandatory = true)]
        public string Id { get; private set; }

        [TikProperty("message", IsReadOnly = true, IsMandatory = true)]
        public string Message { get; private set; }

        [TikProperty("time", IsReadOnly = true, IsMandatory = true)]
        public string Time { get; private set; }
       
        // ...

Property types

Handled properties should be of some specific supported types or enums. Property setter could be private - reflection is used to set property value.

NOTE: For details about implementation see TikEntityPropertyAccessor methods.

NOTE2: Many mikrotik fields seams to be typed (time, MAC, ...) but finally supports exotic values like none (and these values are different for different mikrotik versions). This is the main reason for many of these properties are left as untyped strings.

Regular types

• string
• int
• long
• bool: supported variants: yes/no (R/O: true/false)

Enums

Engine supports custom enum types, enum items should be decorated with TikEnum attribute to allow R/O mappert to work.

public enum ActionType
{
    [TikEnum("accept")]
    Accept,

    [TikEnum("add-dst-to-address-list")]
    AddDstToAddressList,

Creating custom entity

Convetions

• Class names coresponds with API path.

/ip/firewall/filter is tik4net.Objects.Ip.Firewall.FirewallFilter (class name is taken from last two parts of API path)

For nested classes both sub-namespace and three part names are allowed.

Subnamespace - used when there will be more than two classes in this sub-namespace:

ip/dns - tik4net.Objects.Ip.IpDns
ip/dns/cache - tik4net.Objects.Ip.Dns.DnsCache

Three part names - used when there will be only one class in hypothetical subnamespace:

ip/hotspot/user - tik4net.Objects.Ip.Hotspot.HotspotUser
ip/hotspot/user/profile - tik4net.Objects.Ip.Hotspot.HotspotUserProfile

• Property names coresponds to mikrotik field names.

add-mac-cookie - AddMacCookie

• Enum names coresponds with mikrotik value names

accept - Accept

Tools

You can create entity class manually, but if you want some help, see this wiki page.