Getting started

Getting started

A step-by-step first project: from an empty console app to reading and changing data on a real MikroTik router. If you already know your way around .NET and just want the API overview, jump to How to use tik4net instead.

This tutorial uses the high-level O/R mapper (the recommended API). The same operations in the low-level and ADO.NET-like APIs are on the CRUD examples for all APIs page.

---

1. Create a project and add the package

dotnet new console -n MyTikApp
cd MyTikApp
dotnet add package tik4net.entities

tik4net.entities is the high-level O/R mapper; it pulls in the core tik4net package automatically. You only need the other packages for specific scenarios:

Package	When you need it
tik4net	low-level / ADO.NET-like API only, no typed entities
tik4net.entities	typed entities + CRUD (this tutorial)
tik4net.ssh	the Ssh transport (separate because of the Renci.SshNet dependency)
tik4net.testing	unit tests without a live router (TikFakeConnection)

RouterOS setup: the default Api transport needs the API service enabled on the router (/ip/service → api, TCP port 8728). It is enabled by default on most installs. The Api transport handles both the modern (RouterOS v6.43+) and legacy login automatically.

2. Open a connection

Everything starts from an ITikConnection, created by ConnectionFactory. Always dispose it (using) so the socket and login session are released.

using tik4net;

const string Host = "192.168.88.1";
const string User = "admin";
const string Pass = "";   // your router password

using (ITikConnection connection = ConnectionFactory.OpenConnection(TikConnectionType.Api, Host, User, Pass))
{
    ITikCommand cmd = connection.CreateCommand("/system/identity/print");
    Console.WriteLine("Connected to: " + cmd.ExecuteScalar());
}

Run it with dotnet run. If it prints your router's identity, the connection works.

Want a different transport (REST, SSH, Telnet, WinBox…)? Only the TikConnectionType value changes — the rest of your code stays the same. See Connection types & capabilities.

3. Read typed data

Instead of parsing raw output, load strongly-typed entities with LoadAll<T>():

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

using (ITikConnection connection = ConnectionFactory.OpenConnection(TikConnectionType.Api, Host, User, Pass))
{
    foreach (Interface iface in connection.LoadAll<Interface>())
        Console.WriteLine($"{iface.Name}\t{iface.Type}\trunning={iface.Running}");
}

Each entity class (Interface, FirewallFilter, QueueTree, …) maps to a RouterOS path and its fields. See High-level API entities for the built-in types, or custom entities to map a path that isn't covered yet.

4. Filter the data

Use LoadList<T>() with query parameters to let the router do the filtering:

using tik4net.Objects.Ip.Firewall;

// Only firewall address-list entries on the "blocked" list
var blocked = connection.LoadList<FirewallAddressList>(
    connection.CreateParameter("list", "blocked"));

foreach (var item in blocked)
    Console.WriteLine(item.Address);

5. Create, update, delete (CRUD)

using tik4net;
using tik4net.Objects;
using tik4net.Objects.Ip.Firewall;

using (ITikConnection connection = ConnectionFactory.OpenConnection(TikConnectionType.Api, Host, User, Pass))
{
    // CREATE
    var entry = new FirewallAddressList
    {
        Address = "10.20.30.40",
        List = "blocked",
        Comment = "added by tik4net",
    };
    connection.Save(entry);                       // INSERT — fills entry.Id
    Console.WriteLine("Created id " + entry.Id);

    // UPDATE — Save() on an entity that already has an Id performs an update
    entry.Comment = "updated by tik4net";
    connection.Save(entry);                        // sends only changed fields (change tracking, 4.0)

    // DELETE
    connection.Delete(entry);
}

Save<T>() decides insert vs. update from whether the entity has an Id. In 4.0, an update sends only the fields that changed since load, and a no-op Save skips the API call entirely (see Change tracking).

Making risky changes? Wrap them in Safe Mode so RouterOS rolls everything back if your connection drops before you commit — your protection against locking yourself out.

6. Where to go next

• High-level API with O/R mapper — the full typed API.
• CRUD examples for all APIs — the same operations at all three API levels.
• High-level API advanced — async/streaming commands (torch), ordered lists, list merging.
• Connection types & capabilities — pick a transport (REST, SSH, WinBox, MAC-Telnet…) and see what each one supports.
• Exception handling — the error model and exception tree.
• Communication debugging & testing — tik4net.testing and protocol tracing.