Registering Items

To enable a plugin to provide metrics, the metrics must first be registered with MoBro.
This applies to all available item types.

Available Items

The following IMoBroItems can be registered:

• Metric - Represents a single data value provided by a plugin.
• MetricType - Specifies the type of a metric, including its value type and applicable units.
• Category - Categorizes items of a similar type.
• Group - Groups items within a shared context.
• Resource - Represents a file-based item (e.g., an icon or image).
• Action - A triggerable item that executes a certain action.

Creating and Registering Items

The easiest way to create any item is by using the MoBroItem builder available in the SDK.
Once created, items are registered with MoBro through the IMoBroService.

Example: Creating and Registering a Metric

// Create a new metric
var metric = MoBroItem
  .CreateMetric() // Define the type of item: Metric
  .WithId("first_metric") // Assign a unique item ID
  .WithLabel("Metric", "My first metric") // Set the label and an optional description
  .OfType(CoreMetricType.Text) // Use the core 'Text' metric type
  .OfCategory(CoreCategory.Miscellaneous) // Use the 'Miscellaneous' category
  .OfNoGroup() // Specify that this metric does not belong to a group
  .Build();

// Register the metric with MoBro
_mobro.Register(metric);

Example: Creating and Registering an Action

// Create a new action
var action = MoBroItem
  .CreateAction() // Define the type of item: Action
  .WithId("set_metric_value") // Assign a unique item ID
  .WithLabel("Set the metric value") // Set the label and an optional description
  .OfNoCategory() // Assign to the default 'Miscellaneous' category
  .OfNoGroup() // Specify that this action does not belong to a group
  .WithMetric("first_metric") // The metric representing the value adjusted by this action
  .WithHandler(settings => // The handler that is called whenever this action is invoked
  {
    var value = settings.GetValue<string>("value"); // Retrieve the value of the action's setting
    _mobro.UpdateMetricValue("first_metric", value);
  })
  .WithSetting(setting => setting // Add a 'string' setting to the action
    .WithName("value")
    .WithLabel("New value")
    .AsRequired()
    .OfTypeString()
    .Build()
  )
  .Build();

// Register the action with MoBro
_mobro.Register(action);

For all options of actions, including asynchronous handlers, see Reference: Action.

---

Important Notes

• When registering a metric, only its metadata is passed to MoBro, not its value.
  This allows MoBro to know the metrics provided by a plugin even if:
  • A value is currently unavailable.
  • Value retrieval requires additional processing time.
• The actual value of a metric is updated separately. Refer to Updating Metric Values.
• Each item is registered only once. Registering another item with an already registered ID has no effect. To replace an item, unregister it first.

Best Practice

Register all metrics, categories, and custom items in the Init function of the plugin. This ensures that everything is registered before metric values are updated.

---

Referencing Custom Items

In addition to core categories and metric types, custom items can be created and registered as well.
An item must be registered before (or together with) any item referencing it.

Example: Registering Custom Items

// Create a custom category
var financeCategory = MoBroItem
  .CreateCategory() // Type of item: Category
  .WithId("finance_category") // Unique category ID
  .WithLabel("Finances") // Category label
  .Build();

// Create a custom metric type for coins (1 Gold = 100 Silver)
var coinType = MoBroItem
  .CreateMetricType()
  .WithId("coin_type") // Unique metric type ID
  .WithLabel("Coins") // Type label
  .OfValueType(MetricValueType.Numeric) // Value type: Numeric
  .WithBaseUnit(baseUnit => baseUnit // Define the base unit
    .WithLabel("Gold") // Base unit label
    .WithAbbreviation("G") // Base unit abbreviation
    .Build())
  .WithDerivedUnit(derivedUnit => derivedUnit // Add a derived unit
    .WithConversionFormula("x * 100", "x / 100") // Conversion formulas (from base, to base)
    .WithLabel("Silver") // Derived unit label
    .WithAbbreviation("S") // Derived unit abbreviation
    .Build())
  .Build();

// Create a new metric
var metric = MoBroItem
  .CreateMetric()
  .WithId("coin_metric") // Unique ID
  .WithLabel("Coins", "Number of coins") // Label with optional description
  .OfType(coinType) // Use the custom metric type
  .OfCategory(financeCategory) // Associate with the custom category
  .OfNoGroup() // No group for this metric
  .Build();

// Register items in the right order
_mobro.Register(financeCategory); // Register the custom category first
_mobro.Register(coinType); // Register the custom metric type next
_mobro.Register(metric); // Finally, register the metric

---

Validation and Limits

Every item is validated when it is registered. The most important rules are:

Rule	Limit
IDs	Length 1 - 256, only letters, digits, _, . and - (pattern ^[\w\.\-]+$), unique within the plugin.
Labels	Length 1 - 64. Longer labels are truncated automatically.
Descriptions	Max. 256 characters.
References	Referenced types, categories, groups, icons and metrics must be core items or already registered.
Core items	Custom categories and metric types can't use the ID of a core category or core metric type.
Units	Max. 32 units per metric type. Conversion formulas must contain x.
Action settings	Max. 32 settings per action.
Sub-categories/groups	Max. 10 per category or group.
Resources	Files must exist and be located inside the plugin's directory.

The detailed restrictions of every property are listed on the respective type reference pages.

Invalid items are skipped

Inside MoBro, an item that fails validation is not registered and a warning is written to the plugin log. This also affects all items referencing it.
When running the plugin locally, a MoBroItemValidationException is thrown instead. Always run your plugin locally once to catch invalid items early.

---

Using Icons

info

While icons are supported, their usage in the MoBro application is currently limited.

For certain items, such as Categories or MetricTypes, an icon can be assigned.
Before assigning an icon, it must be registered as a Resource.

Example: Assigning an Icon to a Category

// Create the icon resource
var categoryIcon = MoBroItem
  .CreateResource()
  .WithId("category_icon") // Unique resource ID
  .WithAlt("Icon") // Alternative text
  .Icon() // Specify that this resource is an icon
  .AddFromRelativePath("./path/to/icon.png", IconSize.Default) // Path to the icon file
  .Build();

// Create a custom category with an assigned icon
var category = MoBroItem
  .CreateCategory()
  .WithId("finance_category") // Unique category ID
  .WithLabel("Finances") // Category label
  .WithIcon("category_icon") // Reference the icon by ID
  .Build();

// Register the icon and category
_mobro.Register(categoryIcon);
_mobro.Register(category);

---

Unregistering Items

Registered IMoBroItems can be unregistered at any time using the IMoBroService.

caution

Unregistering metrics during plugin runtime may cause issues if they are already added to dashboards.

Example: Unregistering a Metric

// Unregister a metric by its ID
_mobro.Unregister("my_metric");