Action

An action represents an invokable operation that performs a specific task.

Actions define a handler function that is invoked by MoBro whenever the action is triggered by the user, e.g. by tapping a widget on a dashboard. Handlers can contain any custom logic, such as interacting with external software, launching applications, or executing system commands.

Actions can expose individual settings following the same options and restrictions as plugin settings. The values for these settings are configured by the user and passed to the handler on every invocation.

See also: Registering Items

Properties

Property	Type	Restrictions	Description
Id	string	Required Length: 1 - 256 Pattern: ^[\w\.\-]+$	The unique identifier of the action.
Label	string	Required Length: 1 - 64	The textual name of the action. Longer labels are truncated.
Description	string?	Max length: 256	An optional textual description of the action.
CategoryId	string	Required Length: 1 - 256 Pattern: ^[\w\.\-]+$	The category of this action: a core category or the ID of a registered Category.
GroupId	string?	Length: 1 - 256 Pattern: ^[\w\.\-]+$	An optional group the action belongs to (the ID of a registered Group).
MetricId	string?	Length: 1 - 256 Pattern: ^[\w\.\-]+$	An optional metric representing the value this action adjusts (the ID of a registered Metric).
Handler	Func<IMoBroSettings, Task>	Required	The handler that is executed whenever the action is invoked.
Settings	IEnumerable<SettingsFieldBase>	Max. 32 settings	Settings exposed by this specific action.

Creating an Action

Actions are created using the MoBroItem.CreateAction() builder, which expects the following steps in order:

1. WithId(id)
2. WithLabel(label) or WithLabel(label, description)
3. OfCategory(...) or OfNoCategory() (defaults to CoreCategory.Miscellaneous)
4. OfGroup(...) or OfNoGroup()
5. WithMetric(...) or WithNoMetric()
6. WithHandler(...) for a synchronous handler, or WithAsyncHandler(...) for an asynchronous one
7. Optional: any number of WithSetting(...) calls
8. Build()

Synchronous Handler

var setVolume = MoBroItem
  .CreateAction()
  .WithId("set_volume")
  .WithLabel("Set volume")
  .OfCategory(CoreCategory.Media)
  .OfNoGroup()
  .WithMetric("volume") // the metric showing the value this action changes
  .WithHandler(settings =>
  {
    var volume = settings.GetValue<double>("volume");
    SetSystemVolume(volume); // your own logic
    _mobro.UpdateMetricValue("volume", volume);
  })
  .WithSetting(setting => setting
    .WithName("volume")
    .WithLabel("Volume")
    .AsRequired()
    .OfTypeNumber()
    .WithMin(0)
    .WithMax(100)
    .Build())
  .Build();

_mobro.Register(setVolume);

Asynchronous Handler

Use WithAsyncHandler whenever the action performs asynchronous work, such as calling a web API:

var refresh = MoBroItem
  .CreateAction()
  .WithId("refresh_rates")
  .WithLabel("Refresh exchange rates")
  .OfNoCategory()
  .OfNoGroup()
  .WithNoMetric()
  .WithAsyncHandler(async settings =>
  {
    var rates = await _apiClient.GetExchangeRatesAsync();
    _mobro.UpdateMetricValue("usd_eur", rates.UsdEur);
  })
  .Build();

Handler Guidelines

• Catch exceptions inside the handler. An exception escaping a handler can stop the plugin, just like any other unhandled exception. See Error Handling.
• Keep synchronous handlers short. Long-running or I/O-bound work belongs in an asynchronous handler.
• Action settings values are passed to the handler as an IMoBroSettings instance. These are not the plugin settings.
• Actions can be tested locally without MoBro by calling InvokeAction on the local test wrapper.