Application Data and Troubleshooting

Application Data, Settings, and Troubleshooting

Application Settings page

End users normally do not need to edit JSON by hand. Select the cog button to the right of Manage Receivers on the main toolbar to open Application Settings.

The page contains:

• Notification display duration.
• Log retention days.
• Log level.
• Plugin installation directory.
• Plugin data directory.
• Receiver storage directory.
• Receiver JSON filename.
• Configuration scope.

Select Save Settings to write changed values. The button remains disabled until something changes.

User and workstation configuration

Simulcast Utility uses two appsettings.json files as layered configuration:

1. The appsettings.json beside the installed application supplies workstation defaults.
2. %LOCALAPPDATA%\SimulcastUtility\appsettings.json contains overrides for the current Windows user.

When both files define the same setting, the current user's value takes precedence. This allows administrators to establish sensible workstation defaults without overwriting individual preferences.

Application Settings defaults to User scope. When the application is not elevated, User is the only available scope. If Simulcast Utility is launched as administrator, the scope selector also offers Workstation.

Scope	File	Who it affects
User	%LOCALAPPDATA%\SimulcastUtility\appsettings.json	Current Windows user only
Workstation	appsettings.json beside the application executable	Default for every user without an override

System administrators can edit the workstation file manually. End users should normally use the Settings page, which safely creates and updates their local file.

A workstation change does not replace an existing user override. Remove or update the corresponding user value if the new workstation default should take effect for that account.

Settings applied at runtime

Most settings apply without restarting:

• Notification duration affects newly created notifications.
• Log retention cleanup runs after saving.
• Changing receiver directory or filename reloads receivers immediately.
• Changing plugin directory unloads current plugins and loads plugins found in the new directory.
• Changing plugin data directory unloads plugins, creates new data-store contexts, and reloads data already present in that directory.

Log level requires an application restart. The selected value is saved immediately but the current logging pipeline continues using the level with which it started.

Missing plugin and plugin-data directories are created automatically. A missing receiver JSON file is treated as a new, empty receiver collection. Receiver storage filenames must be valid .json filenames.

Existing files are not automatically moved when a directory changes. Copy them manually before saving the new path if the new location should begin with the current receivers, plugins, or plugin data.

Default settings

The bundled workstation appsettings.json starts with values equivalent to:

{
  "ReceiverStorage": {
    "Directory": "%LOCALAPPDATA%\\SimulcastUtility",
    "FileName": "receivers.json"
  },
  "Logging": {
    "Directory": "%LOCALAPPDATA%\\SimulcastUtility\\Logs",
    "RetentionDays": 5
  },
  "Plugins": {
    "Directory": "%LOCALAPPDATA%\\SimulcastUtility\\Plugins",
    "DataDirectory": "%LOCALAPPDATA%\\SimulcastUtility\\PluginData",
    "StateFileName": "plugin-state.json"
  },
  "Notifications": {
    "DisplayDurationSeconds": 3
  },
  "Serilog": {
    "MinimumLevel": {
      "Default": "Debug",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning"
      }
    }
  }
}

%LOCALAPPDATA% in the example represents the current user's Local AppData directory. Some directory properties are supplied by built-in defaults and may be omitted from the bundled JSON until explicitly changed.

Supported log levels are:

• Verbose
• Debug
• Information
• Warning
• Error
• Fatal

Default data locations

Data	Default location
User settings	%LOCALAPPDATA%\SimulcastUtility\appsettings.json
Receivers	%LOCALAPPDATA%\SimulcastUtility\receivers.json
Logs	%LOCALAPPDATA%\SimulcastUtility\Logs
Plugins	%LOCALAPPDATA%\SimulcastUtility\Plugins
Plugin settings and data	%LOCALAPPDATA%\SimulcastUtility\PluginData

The Open Plugin Directory action always resolves the currently effective plugin directory, creates it if necessary, and opens it in File Explorer.

Receiver appears offline

• Verify its IPv4 address and numeric device receiver ID.
• Confirm that the receiver is reachable from the workstation.
• Refresh the receiver and inspect the notification.
• Review the receiver connection/activity badges and current session log.

Receivers disappeared after changing storage

The application immediately loaded the newly configured JSON file. If that file did not exist, an empty receiver collection was expected.

To use existing receivers:

1. Locate the previous receivers.json.
2. Copy it to the new receiver directory, using the configured filename.
3. Save the storage settings again or restart the application.

Plugin does not load

• Confirm that the DLL contains a public, non-abstract ISimulcastPlugin implementation.
• Confirm that its permanent identifier is valid, non-empty, and unique.
• Do not package private copies of Simulcast Utility contract assemblies.
• Include required private managed and native dependencies beside the plugin.
• Review the Plugin.<plugin name> category in the current log.

Plugin disappeared after changing directories

Changing the plugin directory performs a full unload and reload. Only plugins located in the new effective directory are loaded. The directory is created automatically when it does not exist.

Use Open Plugin Directory to verify the active location, copy or import the desired plugin package, and select Refresh Installed Plugins when needed.

Plugin settings reset after changing plugin data

Plugin settings and data are isolated beneath the configured plugin-data directory. When that directory changes, plugins use data found in the new location. Data from the previous directory is not moved automatically.

Copy the plugin's existing data folder to the new plugin-data directory before switching if those values should be retained.

Plugin cannot unload or delete

Common retained references include event subscriptions, static fields, timers, background tasks, windows, WPF controls, media objects, unmanaged handles, and file watchers. DisableAsync must stop them and release references. Plugins should register cleanup for every inserted UI element.

A workstation setting appears to have no effect

The current user probably has an override for the same key. Open Application Settings under User scope and update it, or remove the corresponding value from:

%LOCALAPPDATA%\SimulcastUtility\appsettings.json

Uninstall data choices

The uninstaller preserves user data by default and offers independent removal choices for plugins/plugin data and receivers. Logs are preserved.