vatSys Toolbox contains the code that many vatSys plugins need. It has these features:
- Error reporting: Write errors to the log, and show them in the vatSys error window.
- Clock: Get the current time from a clock that you can replace in tests.
- Windows: Show WPF views in native vatSys windows.
- Styles and controls: WPF styles and controls inherit the style defined in the loaded vatSys profile.
- Background work: Background work and queue abstractions.
- Messages between plugins: Send messages, requests, and broadcasts to other plugins in the same vatSys process.
- Configuration: Find configuration files in the vatSys profile.
- DPI awareness: Make sure that WPF content in vatSys has the correct scale.
Integrations:
- MediatR: Handle the messages from other plugins with MediatR (in the
vatSysToolbox.MediatRpackage).
The toolbox is available from the GitHub Packages NuGet feed.
-
Make a GitHub personal access token (classic) with the
read:packagesscope. -
Add the feed to the
nuget.configfile of your plugin:<?xml version="1.0" encoding="utf-8"?> <configuration> <packageSources> <add key="YuKitsune" value="https://nuget.pkg.github.com/YuKitsune/index.json" /> </packageSources> <packageSourceCredentials> <YuKitsune> <add key="Username" value="%GITHUB_USERNAME%" /> <add key="ClearTextPassword" value="%GITHUB_TOKEN%" /> </YuKitsune> </packageSourceCredentials> </configuration>
-
Add the package to your plugin project:
dotnet add package vatSysToolbox
The toolbox targets .NET Framework 4.7.2, and it references vatSys.exe. Set the VatSysPath MSBuild property to the vatSys installation directory if vatSys is not installed in the default location.
Important
Merge the toolbox into your plugin assembly (for example, with ILRepack). Other plugins can use different versions of the toolbox. If you do not merge the toolbox, vatSys can load the incorrect version.
Register the features that your plugin uses in a ServiceCollection from Microsoft.Extensions.DependencyInjection. Each feature has an extension method, and you can chain the calls. You must also register the logging services.
var services = new ServiceCollection()
.AddLogging()
.AddErrorReporter("My Plugin") // The name that shows with the errors
.AddClock()
.AddWindowManager()
.AddWorkQueue()
.AddPluginMessenger("dev.example.my-plugin"); // The mailbox name of your pluginIf you do not register an error reporter, the other features ignore their errors.
In the larger features, Usage tells you how to use the feature, and Notes has the details that you need only sometimes.
IErrorReporter writes errors to the log, and shows them in the vatSys error window. The error window shows each error message one time each minute at most.
errorReporter.ReportError(exception, "Could not load the configuration");IClock gives the current time in UTC. Use a fake clock in tests.
Use WindowManager to open a WPF view in a vatSys window. Each is identified by a key.
windowManager.OpenOrFocus(
key: "my-plugin.settings",
title: "Settings",
createView: windowHandle => new SettingsView(new SettingsViewModel(windowHandle)),
new WindowOptions { Size = WindowSize.Absolute(400, 300), CanMinimise = false });Openopens the window.OpenOrFocusopens the window, or focuses it if it is already open.Toggleopens the window, or closes it if it is already open. If the window is minimised,Togglefocuses it.IsOpentells you if the window is open.Closecloses the window.
WindowOptions sets these options of the window:
Size:WindowSize.Content(the default) gives the window the size of the view, and the user cannot change it.WindowSize.Absolute(width, height)gives the window a size that the user can change.CanClose,CanMinimise, andCanSendToBackshow or hide the close, minimise, and send-to-back buttons.MiddleClickToClose: a middle-click on the window background closes the window. The default isfalse.MinimumSizeandMaximumSizeset the limits of the size that the user can give the window. Use them only withWindowSize.Absolute.
The view receives an IWindowHandle. Give it to the view model, so that the view model can control its window:
FocusandClosefocus and close the window.Shownoccurs when the window shows for the first time. WPF controls in the window can get the keyboard focus only after this event.Movedoccurs when the window moves.BeforeCloseoccurs when the window is about to close. SetCanceltotrueto keep the window open. Some closes cannot be cancelled (for example, when vatSys closes).
Use ShowPopup to show a WPF view in a small popup at the mouse cursor. You can provide an offset using PopupOptions. The popup has no border or title bar, and it closes when the user clicks outside it. Use the IWindowHandle to close the popup from the view or the view model.
windowManager.ShowPopup(windowHandle => new MyPopupView(new MyPopupViewModel(windowHandle)));When the window closes, it disposes the view model (the DataContext of the view) if the view model is IDisposable or IAsyncDisposable.
Add the styles to the resources of your view:
<UserControl.Resources>
<ResourceDictionary Source="/vatSysToolbox;component/Styles.xaml" />
</UserControl.Resources>Use the VatSysColour markup extension to get a colour from the vatSys profile:
<TextBlock Foreground="{toolbox:VatSysColour InteractiveText}" />VatSysFont gives the font of the vatSys windows. Bevel gives the brushes and the sizes of the vatSys bevels.
The toolbox also contains these controls: BeveledBorder, BeveledLine, Chevron, CustomScrollBar, and TextInput.
To keep the mouse cursor in a text box while the text box has the keyboard focus, set CursorCapture.IsEnabled on a TextBox, or CapturesCursor on a TextInput. The cursor moves to the center of the text box. Enter, Escape, or a middle-click releases the cursor.
<TextBox controls:CursorCapture.IsEnabled="True" />
<controls:TextInput CapturesCursor="True" />WorkQueue does work items one at a time, in the sequence that they were added. Work items that change the same state do not need a lock if they use the same queue.
workQueue.Enqueue(async () => await UpdateSequence());BackgroundTask runs a long-running worker that you can start and stop. Make one for each worker.
IPluginMessenger sends messages to other plugins in the same vatSys process. The messages stay in memory.
SendAsyncsends a message to one plugin.BroadcastAsyncsends a message to all the other plugins.RequestAsyncsends a request to one plugin, and waits for the reply.SendandBroadcastsend a message, but do not wait for the recipient to handle it. If the message cannot be sent, they throw an exception.
The content of a message is optional. If you do not give content, the message has an empty payload and an empty content type.
Each plugin has an inbound queue. If the recipient is not ready, the message stays in its queue until the recipient calls Start. Add your handlers before you call Start.
var json = new JsonMessageSerializer();
messenger.Subscribe("dev.example.my-plugin.sequence-updated", (message, cancellationToken) =>
{
var sequence = message.Deserialize<Sequence>(json);
return Task.CompletedTask;
});
messenger.Handle("dev.example.my-plugin.get-sequence", (request, cancellationToken) =>
Task.FromResult(json.ToContent(GetSequence())));
messenger.Start();
await messenger.BroadcastAsync("dev.example.my-plugin.sequence-updated", sequence, json);
var reply = await messenger.RequestAsync("OtherPlugin", "dev.example.other-plugin.get-status", query, json);Other plugins use the mailbox name of your plugin to send messages to it. Use a reverse DNS name for the mailbox name.
Use a reverse domain name as the prefix of each message type (for example, dev.example.my-plugin.sequence-updated). This prevents conflicts between plugins.
The message data is bytes. Each message has a content type, so plugins can use different formats. The toolbox contains JsonMessageSerializer. To use a different format (for example, MessagePack), implement IMessageSerializer. If a handler accepts more than one format, give all the serializers to Deserialize:
var sequence = message.Deserialize<Sequence>(json, messagePack);If a plugin receives a direct message or a request that it has no handler for, it logs a warning. The sender of a direct message is not told. The requester of a request receives a MessagingException, so that it does not wait forever.
Use IPluginMessenger only for messages that go to other plugins, or come from other plugins.
For messages between the components in your plugin (for example, from a view model to the plugin class), use a different messenger.
flowchart LR
subgraph vatSys["vatSys process"]
subgraph MyPlugin["My plugin"]
ViewModel["View model"]
Service["Service"]
PluginClass["Plugin class"]
Internal{{"Internal messenger"}}
Messenger{{"IPluginMessenger"}}
ViewModel <--> Internal
Service <--> Internal
PluginClass <--> Internal
PluginClass <--> Messenger
end
Transport(["Message transport"])
OtherPlugin["Other plugin"]
Messenger <--> Transport
Transport <--> OtherPlugin
end
The two kinds of messages have different properties:
IPluginMessenger |
Internal messenger | |
|---|---|---|
| Recipients | Other plugins | Components in the same plugin |
| Data | Bytes, with a content type. You must serialize the data. | .NET objects. |
| Delivery | The message goes into a queue. A background thread handles it later. | The messenger usually calls the handlers immediately, on the same thread. |
| Contract | The message type and the payload are a public contract. Other plugins can depend on them. | You can change the messages at any time. |
The toolbox does not contain an internal messenger. Use the messenger that you prefer. We recommend WeakReferenceMessenger from the CommunityToolkit.Mvvm package. You can also use MediatR notifications, or .NET events.
// A message inside the plugin
public record WindowOpenedMessage;
// The view model sends the message
WeakReferenceMessenger.Default.Send(new WindowOpenedMessage());
// The plugin class receives the message, and tells the other plugins
WeakReferenceMessenger.Default.Register<Plugin, WindowOpenedMessage>(this, (plugin, _) =>
plugin._messenger.Broadcast("dev.example.my-plugin.window-opened"));The Tag List plugin uses this pattern.
ConfigurationLocator finds a configuration file. It searches these directories in this sequence:
Profile\Plugins\Configs\<Plugin Name>Profile\Plugins\ConfigsProfile\PluginsProfile- The directory of the plugin assembly
var configurationFilePath = ConfigurationLocator.LocateConfigurationFile(this, "MyPlugin.json");WPF content in vatSys has the correct scale only if Windows runs vatSys as a DPI-unaware application. Call DpiAwareness.EnsureDpiAwareness() when your plugin starts. This method sets the Windows compatibility setting for vatSys.exe. If the setting changes, the method restarts vatSys.
The vatSysToolbox.MediatR package sends the messages and the requests from other plugins to MediatR handlers. Add the package to your plugin project:
dotnet add package vatSysToolbox.MediatRThe package uses MediatR 12. Merge MediatR into your plugin assembly too.
Connect each message type to a notification or a request:
var json = new JsonMessageSerializer();
// All the INotificationHandler<SequenceUpdatedNotification> handlers receive each message
messenger.SubscribeNotification<SequenceUpdatedNotification>("dev.example.other-plugin.sequence-updated", mediator, json);
// The IRequestHandler<GetSequenceRequest, Sequence> handler gives the reply to each request
messenger.HandleRequest<GetSequenceRequest, Sequence>("dev.example.my-plugin.get-sequence", mediator, json);
messenger.Start();You can also put the message type on the handler with an attribute, and connect all the handlers in an assembly:
[PluginMessageHandler("dev.example.other-plugin.sequence-updated")]
public class SequenceUpdatedHandler : INotificationHandler<SequenceUpdatedNotification>
{
public Task Handle(SequenceUpdatedNotification notification, CancellationToken cancellationToken) { ... }
}
[PluginMessageHandler("dev.example.my-plugin.get-sequence")]
public class GetSequenceHandler : IRequestHandler<GetSequenceRequest, Sequence>
{
public Task<Sequence> Handle(GetSequenceRequest request, CancellationToken cancellationToken) { ... }
}
messenger.SubscribeHandlers(typeof(Plugin).Assembly, mediator, json);
messenger.Start();MediatR publishes a notification to all the handlers of its class. Thus, all the handlers of the notification receive the messages, also the handlers that do not have the attribute.
The serializer converts the payload to the notification or the request, and the response to the reply. The handlers run on the thread of the messenger. Use IGuiInvoker to change the UI from a handler (see The UI thread).
vatSys and all the plugins use one UI thread. IGuiInvoker does an action on that thread. Do not use IGuiInvoker unless you must.
You must use IGuiInvoker only if both of these conditions are true:
- The code can run on a thread that is not the UI thread. For example:
OnFDRUpdateandOnRadarTrackUpdate- The
Networkevents - The plugin messenger handlers and the MediatR handlers
WorkQueue,Task.Run,System.Timers.Timer, and code afterConfigureAwait(false)- Some vatSys events, for example
MMI.SelectedTrackChanged. These can occur on any thread.
- The code changes something that must change on the UI thread:
- A WinForms form or control, or a WPF element. For example, it makes, shows, or closes a window.
- The state that a WPF view binds to. For example, a view model property or collection.
- A vatSys menu item, or something that is only for the UI thread, such as a message filter.
Do not use IGuiInvoker in these cases:
- The code always runs on the UI thread. For example: WinForms and WPF event handlers, menu item clicks, form events,
Application.Idle, and aDispatcherTimer. On the UI thread the action runs immediately, so the call does nothing. Call the code directly, and catch the exceptions, because an exception that is not caught on the UI thread stops vatSys. - The code does not change the UI. For example, it reads or changes plugin data, or it sends a message.
- A method that you call already goes to the UI thread. For example,
WindowManageropens and closes windows on the UI thread. - The UI does not change. Do the checks on the background thread first. For example, if a window shows one aircraft, do not post the updates of the other aircraft.
From a thread that is not the UI thread, each call posts one message to the UI thread. A thread can have a maximum of 10,000 posted messages. If the queue becomes full, the WPF content in vatSys can stop until vatSys restarts. Thus, do not call IGuiInvoker for each radar track update or each flight plan update.
Run the build script from the root of the repository:
./build.sh CompileThe build downloads vatSys if you do not set the VatSysPath parameter.