Settings Dialog

This guide shows how to implement a settings screen that the user can open from the Plugin menu.

Enable the Settings menu item

Set HasSettings = true in GetInfo. HydroSym automatically adds a Settings item to your plugin's menu — you do not declare it in Menus.

public override GetInfoResponse GetInfo()
{
    return new GetInfoResponse
    {
        // ...
        HasSettings = true,
    };
}

Implement ShowSettings

public override ShowSettingsResponse ShowSettings(ShowSettingsRequest request)
{
    ShowSettingsResponse? result = null;
    var thread = new Thread(() =>
    {
        Application.EnableVisualStyles();
        var owner = new NativeWindowWrapper(new IntPtr(request.ParentWindowHandle));
        var dialog = new SettingsDialog(request.ConfigPath);
        dialog.ShowDialog(owner);
        result = new ShowSettingsResponse
        {
            RestartRequired = dialog.RestartRequired,
        };
    });
    thread.SetApartmentState(ApartmentState.STA);
    thread.Start();
    thread.Join();

    return result ?? new ShowSettingsResponse();
}

Read and write config

Use configPath from the ShowSettings request (and also from Initialize) to locate your config file:

public partial class SettingsDialog : Form
{
    private readonly string _configPath;
    public bool RestartRequired { get; private set; }

    public SettingsDialog(string? configPath)
    {
        _configPath = configPath
            ?? Path.Combine(
                Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData),
                "HydroSym", "plugins", "acme", "acme.ini");

        InitializeComponent();
        LoadSettings();
    }

    private void LoadSettings()
    {
        var ini = IniFile.Load(_configPath);
        serverBox.Text   = ini["Database", "Server"];
        databaseBox.Text = ini["Database", "Database"];
        integratedAuthCheck.Checked = bool.Parse(
            ini["Database", "IntegratedSecurity"] ?? "true");
    }

    private void SaveButton_Click(object sender, EventArgs e)
    {
        var ini = IniFile.Load(_configPath);
        bool serverChanged = ini["Database", "Server"] != serverBox.Text;

        ini["Database", "Server"]            = serverBox.Text;
        ini["Database", "Database"]          = databaseBox.Text;
        ini["Database", "IntegratedSecurity"] = integratedAuthCheck.Checked.ToString();
        ini.Save(_configPath);

        // Connection string changes require restart to take effect
        RestartRequired = serverChanged;
        DialogResult = DialogResult.OK;
        Close();
    }

    private void TestConnectionButton_Click(object sender, EventArgs e)
    {
        try
        {
            var conn = new SqlConnection(
                $"Server={serverBox.Text};Database={databaseBox.Text};Integrated Security=true;");
            conn.Open();
            conn.Close();
            MessageBox.Show("Connection successful.", "Test Connection",
                MessageBoxButtons.OK, MessageBoxIcon.Information);
        }
        catch (Exception ex)
        {
            MessageBox.Show($"Connection failed:\n{ex.Message}", "Test Connection",
                MessageBoxButtons.OK, MessageBoxIcon.Error);
        }
    }
}

The restartRequired flag

Return RestartRequired = true when changes require HydroSym to be restarted (e.g., a new database server address). HydroSym shows a notification to the user:

"Plugin settings have been saved. Restart HydroSym for changes to take effect."

HydroSym does not restart automatically — it just notifies the user.

If the user only changes a non-critical setting (like a display preference), return RestartRequired = false.

Typical settings to expose

Setting	INI key	Notes
Database server	[Database] Server	Restart required on change
Database name	[Database] Database	Restart required on change
Auth type	[Database] IntegratedSecurity	Restart required
Auto check-in	[Options] AutoCheckIn	No restart required
Default currency	[Options] DefaultCurrency	No restart required
Log level	[Logging] Level	No restart required

Config file location

HydroSym passes configPath in both Initialize and ShowSettings. Always use this path — do not hardcode a location. The path is configured in HydroSym's INI file and can be on a network share for centrally-managed deployments.

If configPath is null (not configured in the INI), fall back to a sensible default:

private string ResolveConfigPath(string? configPath)
    => configPath ?? Path.Combine(
        Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData),
        "HydroSym", "plugins", "AcmeErpPlugin", "settings.ini");