Factory and packaging
XyzProviderFactory.cs is the smallest file in a provider project — but it's the one discovery actually looks for. It, plus the assembly metadata described here, is what turns a class library into a loadable SmartHopper provider.
The factory
ProviderManager reflects over each SmartHopper.Providers.*.dll for a public IAIProviderFactory implementation. It has exactly two methods:
public class XyzProviderFactory : IAIProviderFactory
{
// Providers are singletons — return the shared instance.
public IAIProvider CreateProvider() => XyzProvider.Instance;
// Settings are per-instantiation (the dialog binds to one).
public IAIProviderSettings CreateProviderSettings() => new XyzProviderSettings(XyzProvider.Instance);
}
That's it. No registration call, no manifest — the assembly name pattern and the factory type are the whole contract.
Assembly metadata
Community providers declare compatibility via attributes in SmartHopper.ProviderSdk.Metadata:
using SmartHopper.ProviderSdk.Metadata;
[assembly: SmartHopperProviderId("xyz")] // optional stable id (e.g. "openai")
[assembly: BuiltAgainstSdk("1.0.0")] // SDK version you compiled against — REQUIRED
[assembly: MinHostSdk("1.0.0")] // optional minimum host SDK
| Attribute | Required? | Checked |
|---|---|---|
BuiltAgainstSdk | Yes (for the compat model) | Its major version must equal the host SDK major — otherwise SdkCompatibility.Check rejects the assembly before any of its code runs. Omit it and the check reports MissingMetadata. |
MinHostSdk | No | If present, host SDK must be ≥ this version (HostTooOld otherwise). |
SmartHopperProviderId | No | A stable provider id independent of assembly name, used for conflict resolution and classification. Not a security boundary — trust still comes from signature/hash checks. |
The version check is BuiltAgainstSdk.MAJOR == HostSdk.MAJOR && HostSdk >= MinHostSdk. Official in-repo providers get these attributes injected by build tooling; community providers declare them explicitly.
SdkCompatibility.Check currently exists but is not called by the load path — the attributes are unenforced today. Declare them regardless: the check is the intended gate, and declaring costs nothing while making the provider forward-compatible.
Project file
A provider project is a minimal class library targeting both frameworks, referencing only the SDK:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<!-- Output must be named SmartHopper.Providers.<Name>.dll -->
<TargetFrameworks>net7.0-windows;net7.0</TargetFrameworks>
<EnableDynamicLoading>true</EnableDynamicLoading>
<EnableWindowsTargeting>true</EnableWindowsTargeting>
<UseWindowsForms Condition="$(TargetFramework.Contains('-windows'))">true</UseWindowsForms>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="..\SmartHopper.ProviderSdk\SmartHopper.ProviderSdk.csproj" />
<!-- or the SmartHopper.ProviderSdk NuGet package for out-of-repo providers -->
</ItemGroup>
</Project>
Critical details:
- Assembly name is the contract. Output must be
SmartHopper.Providers.<Name>.dll—ProviderManagerdiscovers by that glob, so name your projectSmartHopper.Providers.<Name>. EnableDynamicLoading— required so the assembly resolves its dependencies inside its isolatedAssemblyLoadContext.- Reference only
SmartHopper.ProviderSdk(project reference in-repo, NuGet package out-of-repo). ReferencingSmartHopper.Infrastructure/other host assemblies both bloats the plugin and breaks the SDK boundary.
Deploying
Drop the built SmartHopper.Providers.<Name>.dll into the app-local folder — the directory containing SmartHopper.Infrastructure.dll. That is the only location ProviderManager.DiscoverProvidersAsync scans today (glob SmartHopper.Providers.*.dll).
SmartHopper.ProviderSdk/README.md mentions %AppData%\SmartHopper\Providers\ / ~/.config/SmartHopper/Providers\ as a drop-in location — that path is not implemented in the current loader. Only the app-local folder is discovered.
On next load the pipeline is:
- Authenticode + strong-name check (Windows only; skipped on macOS) — the provider must be signed with the same certificate and strong-name key as the host, or it is rejected outright. This means unsigned/self-built community providers cannot load on Windows today; the community path effectively only works on macOS and DEBUG builds.
- SHA-256 hash verification against the official hash repository →
Match/Mismatch/Unavailable/NotFound, gated byProviderIntegrityCheckMode(Strict/Hardblock;Softwarns and allows; DEBUG forcesSoft). - Trust prompt — unknown assemblies ask "A new AI provider was detected — enable it?" and the answer is stored in
TrustedProviders. - Instantiate —
Assembly.LoadFrom, reflect forIAIProviderFactory, callCreateProvider()/CreateProviderSettings(),RegisterProvider.
Note that the isolated AssemblyLoadContext (ProviderLoadContext), the SdkCompatibility check on BuiltAgainstSdk/MinHostSdk, and the four-way ProviderClassifier (Official/OfficialTampered/Community/Invalid) all exist as code but are not wired into the load path — they're groundwork for the stricter model, not current behavior.
There is no provider sandbox — a loaded provider executes arbitrary .NET in the SmartHopper process (in the default load context today). Write providers assuming they share the process; deploy them assuming users will (rightly) be cautious.
Full-project checklist
-
XyzProviderFactory : IAIProviderFactory— public, parameterless-constructible. -
[assembly: BuiltAgainstSdk("…")]matches the SDK major you build against. - Output name
SmartHopper.Providers.<Name>.dll,<EnableDynamicLoading>. - Only
SmartHopper.ProviderSdkreferenced. -
XyzProvidersetsthis.Models = new XyzProviderModels(this)in its constructor.