🔌 Plugin Development Guide

✦ Quick Start

<ItemGroup>
  <Reference Include="AbigailsMediaRenamer.Contracts">
    <HintPath>C:\Program Files\AbigailsMediaRenamer\AbigailsMediaRenamer.Contracts.dll</HintPath>
    <Private>false</Private>
  </Reference>
</ItemGroup>

The bundled Newznab plugin (a generic usenet-indexer client) is a complete, working IDownloadProvider example. It's not open source, but it ships as AbigailsMediaRenamer.UsenetPlugins.dll right next to Contracts.dll in your install folder — a decompiler (ILSpy, dotPeek) will show you exactly how it's built, or just email me for the source.

✦ The IPlugin base interface

Every plugin — download or metadata — implements this:

public interface IPlugin
{
    string PluginId { get; }        // unique across all plugins, e.g. "MyMetadataProvider"
    string DisplayName { get; }     // shown in Settings
    string Version { get; }         // informational only
    PluginType Type { get; }        // MetadataProvider or DownloadProvider
    string Description { get; }     // shown in Settings
    bool IsEnabled { get; set; }    // set BY the app from saved settings — don't set this yourself
    ConfigField[] GetConfigSchema();
    bool Initialize(Dictionary<string, string> config);
}

• PluginId must be globally unique and stable across versions — it's the key the app uses to persist your plugin's enabled state and config in settings.json. Don't rename it once users have configured your plugin; they'll lose their saved config.
• Type must match the interface you actually implement. The app validates this at load time and logs a warning if Type == DownloadProvider but you don't implement IDownloadProvider (or vice versa) — get it right so your plugin is actually found by the search code, which looks it up by interface, not by Type.
• IsEnabled is a settable property you own, but you don't drive it. The app sets it from the user's saved on/off toggle before calling Initialize. Use Initialize's return value for your own "am I ready" logic instead.

ConfigField and the Settings UI

GetConfigSchema() declares what configuration your plugin needs; the app builds the Settings form for you from this — you never write UI code.

public class ConfigField
{
    public string Key { get; }            // dictionary key passed back into Initialize
    public string Type { get; }           // "string", "url", "bool" — see below
    public string Label { get; }          // field label in the UI
    public string? Placeholder { get; }   // shown as a tooltip/hint
    public bool IsSecret { get; }         // renders as a masked PasswordBox
    public bool IsRequired { get; }       // shows a red "*" — not currently enforced before save
    public string? DefaultValue { get; }
}

Field rendering rules:

• Type == "bool" → checkbox.
• IsSecret == true → password box (masked). Use this for API keys/tokens.
• Anything else (including "string", "url") → a plain text box. Type beyond "bool" is currently informational rather than driving different widgets or validation — don't rely on "url" getting URL-specific validation for free.

Initialize(Dictionary<string, string> config)

Called once at startup, after the user has enabled your plugin and filled in the config form. config contains your ConfigField keys mapped to whatever the user typed (or the field's default, if untouched). One key is injected automatically regardless of your schema:

• config["FlareSolverrUrl"] — the user's global FlareSolverr URL setting (empty string if unset). Don't declare your own ConfigField for this; just read it if your indexer needs Cloudflare bypass, and declare RequiresFlareSolverr => true on IDownloadProvider so the app warns the user if they haven't set one.

Return false if the config is invalid (missing required values, malformed URL, etc.) — the app logs this and skips loading your plugin entirely for that session rather than calling any of your search methods. There's no separate "test connection" button in the current UI, so this is your only validation hook.

✦ Writing a download provider

public interface IDownloadProvider : IPlugin
{
    string[] SupportedContentTypes => Array.Empty<string>(); // default: all types
    bool RequiresFlareSolverr => false;

    Task<List<DownloadResult>> SearchAsync(
        string query,
        CancellationToken cancellationToken = default);
}

• SupportedContentTypes — an array like ["Movie", "TV"] or ["Audiobook"] restricts which library types will query your plugin. Leave the default (empty array) if your indexer searches everything.
• RequiresFlareSolverr — set true if your indexer sits behind Cloudflare and needs the proxy; the download search UI shows a warning banner if FlareSolverrUrl isn't configured.
• SearchAsync is the entire contract. One free-text query in, a flat list of results out — no paging, no separate "get details" call. Return an empty list for "no results"; do throw for real failures (HTTP errors, unparseable responses) — the caller catches and logs it, it just won't crash the app.

public class DownloadResult
{
    public string Title { get; set; }
    public string DownloadLink { get; set; }    // magnet link, .torrent URL, or .nzb URL
    public string? Size { get; set; }           // pre-formatted string, e.g. "4.2 GB" — your job to format
    public int? Seeders { get; set; }           // torrent-specific; leave null for usenet
    public int? Leechers { get; set; }
    public DateTime? UploadedDate { get; set; }
    public string? ProviderName { get; set; }   // shown alongside each result; defaults sensibly if omitted
}

Size is a display string, not bytes — format it yourself (KB/MB/GB thresholds, empty string for zero/unknown is the simplest approach).

✦ Writing a metadata provider

public interface IMetadataProvider : IPlugin
{
    Task<List<SeriesSearchResult>> SearchSeriesAsync(
        string title, int? year = null, CancellationToken cancellationToken = default);

    Task<List<MovieSearchResult>> SearchMovieAsync(
        string title, int? year = null, CancellationToken cancellationToken = default);

    Task<List<EpisodeInfo>> GetSeasonEpisodesAsync(
        string seriesId, int seasonNumber, CancellationToken cancellationToken = default);
}

Your results are merged alongside the built-in providers (TMDB, TVDB, etc.) in the same search — implement whichever of the three methods make sense for your source; return an empty list from the others if, say, you're TV-only.

public class SeriesSearchResult
{
    public string ProviderId { get; set; }   // YOUR id for this series — round-trips back to you
    public string Title { get; set; }
    public int? Year { get; set; }
    public string? Description { get; set; }
    public int? EpisodeCount { get; set; }
    public double? Confidence { get; set; }  // 0-1 if you can score match quality; null is fine
}

ProviderId matters: whatever you put here is the seriesId the app hands back to your own GetSeasonEpisodesAsync later, once the user picks your result — it's not the app's ID, it's yours, so use whatever your backend needs to look the series up again (a slug, a numeric ID, a URL fragment), just be consistent with yourself.

MovieSearchResult is the same shape minus EpisodeCount (movies have no season call). EpisodeInfo (returned from GetSeasonEpisodesAsync) is EpisodeNumber, Title, AirDate, Description — no ProviderId, since there's no further round-trip after this.

✦ Trust and loading model

Understanding this will save you support requests from your plugin's users:

• On every startup, the app SHA-256-hashes every .dll in plugins/ and logs the hash.
• If the hash isn't already trusted, the user gets a blocking prompt naming the file and showing a truncated hash, warning that "plugins run with full application privileges." They must accept for your plugin to load at all that session.
• Once trusted, the hash is remembered — no more prompts, unless the file changes. Any rebuild, even a no-op recompile, changes the hash and re-triggers the prompt. This is deliberate: tell your users to expect a fresh trust prompt after every update you ship, and don't design a plugin that silently self-updates its own DLL — that would look identical to a supply-chain compromise from the trust system's point of view.
• The one exception: a DLL whose filename contains newznab is auto-trusted — a first-party carve-out for the bundled indexer plugin, not something you can opt into by renaming your own DLL. Users should decide to trust your plugin deliberately.
• After trust, the app instantiates your plugin via a public parameterless constructor (required — no dependency injection) and only calls Initialize() if the user has toggled it on in Settings.
• One DLL = one plugin. If your assembly contains multiple IPlugin implementations, only the first one found is loaded — ship one plugin type per DLL.

Multiple instances of the same indexer type

Since trust and config are both keyed by DLL identity, a user who wants to query two different same-protocol indexers just copies the DLL under a second filename — each copy gets its own trust prompt, its own entry in Settings, and its own Initialize() config. You don't need to build multi-instance support into your plugin for this to work, as long as your PluginId and config are self-contained per loaded instance.

✦ Practical notes

• Target the same TFM as the host app or you'll hit assembly load failures.
• Ship your own dependencies alongside your DLL in plugins/ — there's no NuGet restore step at runtime, the loader just loads what's sitting next to your plugin DLL (and what's already loaded in the host process).
• Don't throw from Initialize. Return false instead — an exception there is caught and logged the same as any other plugin error, but a clean false is easier for you to reason about and easier for users to diagnose from the log.
• Logging: your plugin has no direct hook into the app's log file — use exceptions for search failures (the caller catches and logs on your behalf) rather than trying to write to the app's log yourself.
• Networking: use whatever HTTP client library you like. A single static HttpClient reused for the lifetime of your plugin instance is the recommended .NET pattern — avoid creating a new one per search call.