High level API reading data

All data-read methods are implemented as extension methods of ITikConnection and ITikCommand objects. Every method returns some data entities. For details about entities see this wiki page.

• connection.LoadAll: Loads all entity list without filtering.
• connection.LoadSingle: Loads exactly one row (optionally with filter). Throws when zero or more than one row matches.
• connection.LoadSingleOrDefault: Loads one row or returns null when nothing matches.
• connection.LoadById: Loads entity with specified id. Throws TikNoSuchItemException if not found.
• connection.LoadByName: Loads entity with specified name field value. Throws TikNoSuchItemException if not found.
• connection.LoadList: Loads entity list. Could be filtered with filterParameters.
• command.LoadList: --dtto--
• connection.LoadWithDuration: Calls command and reads all returned rows for given period.
• command.LoadWithDuration: --dtto--
• connection.LoadAsync: Calls command and starts a background reading thread. After that returns control to the calling thread. All read rows are returned as callbacks
• command.LoadAsync: -dtto-
• connection.LoadListenAsync: Starts real-time monitoring of an entity list via the RouterOS /listen command. Streams change notifications until cancelled.
• command.LoadListenAsync: -dtto-

LoadAll

Alias to LoadList without filter. You can filter list via LINQ on client side.

// load all QT entities
var queues = connection.LoadAll<QueueTree>();

LoadSingle

Alias to LoadList optionally with filter, ensures that the result contains exactly one row. Throws an exception if the command returns zero or more than one entity.

// there should be exactly one row in response for /system/resource/print
var sysRes = connection.LoadSingle<SystemResource>();

LoadSingleOrDefault

Similar to LoadSingle but returns null if row is not found.

// try to find mangle by its comment
var startMangle = connection.LoadSingleOrDefault<FirewallMangle>(
    connection.CreateParameter("comment", "MY COMMENT"));

LoadById

Loads entity with specified id. Throws TikNoSuchItemException if not found (use LoadSingleOrDefault with an .id filter when you prefer a null result).

//from unittest
connection.Save(filter);

// verify that all values were really written to mikrotik router
var loadedFilter = connection.LoadById<BridgeFilter>(filter.Id);
Assert.IsNotNull(loadedFilter);
Assert.AreEqual(filter.Chain, loadedFilter.Chain);

LoadList

Loads entity list. Could be filtered with filterParameters.

// load all log entries
var logs = connection.LoadList<Log>();
foreach (Log log in logs)
{
    Console.WriteLine("{0}[{1}]: {2}", log.Time, log.Topics, log.Message);
}

LoadWithDuration

Calls command and reads all returned rows for given durationSec period. After this period calls cancel on the MikroTik router and returns all loaded rows. Throws exception if any 'trap' row occurs.

LoadAsync

Calls command and starts a background reading thread. After that returns control to the calling thread. All read rows are returned as callbacks (onLoadItemCallback, onExceptionCallback) from the loading thread.

REMARKS: if you want to propagate loaded values to GUI, you should use some kind of synchronization or Invoke, because callbacks are called from a non-UI thread.

The running load can be terminated by Cancel CancelAndJoin call on command object. Command is returned as result of the method.

var cmd = connection.LoadAsync<ToolTorch>(
    item => Console.WriteLine(item.ToString()), 
    error => Console.WriteLine("ERROR: " + error.ToString()),
    connection.CreateParameter("interface", interfaceName),
    connection.CreateParameter("port", "any"),
    connection.CreateParameter("src-address", "0.0.0.0/0"),
    connection.CreateParameter("dst-address", "0.0.0.0/0"));

    Console.ReadLine();

   cmd.Cancel();

LoadListenAsync

Starts real-time monitoring of an entity list via the RouterOS /listen command. Unlike LoadAsync (which uses /print), /listen sends !re sentences only when an item changes — it never sends !done. Useful for watching interface state, IP address changes, routing table updates, etc.

Deleted items (RouterOS sends =.dead=true) are routed to the optional onDeletedCallback with the item's .id. Stop monitoring by calling Cancel or CancelAndJoin on the returned command.

REMARKS: callbacks are called from a non-UI thread — use synchronization if updating UI.

var listenCmd = connection.LoadListenAsync<Interface>(
    onChangeCallback:    iface => Console.WriteLine($"{iface.Name} changed, running={iface.Running}"),
    onDeletedCallback:   id    => Console.WriteLine($"Interface {id} deleted"),
    onExceptionCallback: ex    => Console.WriteLine("Error: " + ex.Message));

Console.ReadLine(); // listening runs in background thread

listenCmd.CancelAndJoin();