Entity helpers

Entity helpers

The verbs that are not CRUD. Some RouterOS menus do more than hold rows — you ping from one, flush another, take a snapshot of a third — and those actions are extension methods on ITikConnection, grouped here by what you would be doing in WinBox rather than by which class they live on.

⚠️ Alpha — ships in v4.0.0-alpha: tested and functional, but the API may still change before the final 4.0 release. See Connection types & capabilities.

They all need using tik4net.Objects; plus the entity's own namespace. Entities that have helpers are marked ⁵ in the entity reference.

Tools

WinBox	tik4net
Tools → Ping	connection.Ping("10.0.0.1", 4) → IEnumerable<ToolPing>
Tools → Traceroute	connection.Traceroute("10.0.0.1") → IEnumerable<ToolTraceroute>
Tools → Wake on LAN	connection.ExecuteWol("00:11:22:33:44:55", "ether1")

using tik4net.Objects;
using tik4net.Objects.Tool;

foreach (ToolPing reply in connection.Ping("10.0.0.1", 4))
    Console.WriteLine($"{reply.Host}  {reply.Time}  loss={reply.PacketLoss}");

ExecuteWol takes the MAC either as a string or as a MacAddress; the interface is optional.

Log

Reading the log is an entity (Log, /log). Writing to it is a helper — one method per severity, each mapping to the router's own /log info|warning|error|debug:

connection.LogInfo("provisioning started");
connection.LogWarning("unexpected value, using the default");
connection.LogError("could not reach the peer");
connection.LogDebug("rule 4 matched");

Useful for leaving a trace of your own changes where the router's admin will actually look for it.

Monitors — one reading instead of a stream

monitor in the CLI runs until you stop it. When all you want is the current values, these take a single snapshot and return:

using tik4net.Objects.Interface;
using tik4net.Objects.Interface.Ethernet;

InterfaceMonitorTraffic t = connection.GetInterfaceMonitorTrafficSnapshot("ether1");
Console.WriteLine($"{t.RxBitsPerSecond} / {t.TxBitsPerSecond}");

EthernetMonitor e = connection.GetEthernetMonitorSnapshot("ether1");
Console.WriteLine($"{e.Status}  {e.Rate?.Value} bit/s  full-duplex={e.FullDuplex}");

var p = connection.GetInterfacePppoeClientMonitorSnapshot("pppoe-out1");

For a continuous stream — torch, or a monitor you keep open — use LoadWithCallback instead. That needs the Listen capability, which every transport declares, though only the binary API pushes; the rest poll. See connection types & capabilities.

Caches and snapshots

connection.FlushDnsCache();          // /ip/dns/cache/flush
connection.TakeAccountingSnapshot(); // /ip/accounting/snapshot/take

TakeAccountingSnapshot is the one that matters for correctness: /ip/accounting/snapshot is only refreshed when you ask for it, so reading the snapshot entity without taking one first gives you the previous reading.

Packages

using tik4net.Objects.System;

SystemPackage wireless = connection.LoadList<SystemPackage>()
    .Single(p => p.Name == "wireless");

connection.Disable(wireless);
connection.Enable(wireless);
// both take effect on the next reboot — RouterOS does not enable a package live

IPsec keys

RSA key management on /ip/ipsec/key, which is file-based rather than row-based:

using tik4net.Objects.Ip.Ipsec;

connection.GenerateIpsecKey("peer-a");                       // key size defaults to 2048
connection.ExportIpsecPublicKey("peer-a", "peer-a-pub.pem"); // writes to the router's file system
connection.ImportIpsecKey("peer-b", "peer-b-pub.pem");       // optional passphrase for a private key

Export and import work against files on the router, so pair them with /file (the File entity) to get the result off the box.

Writing your own

A helper is a plain extension method that builds a command — nothing privileged:

public static class MyMenuConnectionExtensions
{
    public static void DoTheThing(this ITikConnection connection, string name)
    {
        ITikCommand cmd = connection.CreateCommand("/my/menu/do-the-thing",
            connection.CreateParameter("name", name, TikCommandParameterFormat.NameValue));
        cmd.ExecuteNonQuery();
    }
}

Name the class after the entity it serves — MyMenuConnectionExtensions for MyMenu. That is the convention the entity reference's ⁵ marker is derived from, and a unit test holds it, so a helper class named after the wrong entity fails the build rather than going unlisted.

See also

• Entity reference — which menus are covered, and which have helpers
• Entity value types — MacAddress, TikDuration and the rest
• High-level API advanced — streaming reads, ordered lists, list merging
• Custom entities — writing the entity a helper belongs to