LANCommander.Server.Plugins 2.2.0-beta.3

LANCommander.Server.Plugins

The contracts a LANCommander server plugin compiles against. A server plugin needs this package, LANCommander.SDK, and, for pages, LANCommander.Server.UI. All three are loaded by the server, so reference them with ExcludeAssets="runtime" to keep them out of the plugin's folder:

<PackageReference Include="LANCommander.SDK" Version="..." ExcludeAssets="runtime" />
<PackageReference Include="LANCommander.Server.Plugins" Version="..." ExcludeAssets="runtime" />
<PackageReference Include="LANCommander.Server.UI" Version="..." ExcludeAssets="runtime" />

Use the version of the server the plugin targets.

A plugin with a context needs DataId and MigrationAssemblies in its [LANCommanderPlugin] attribute. Plugin settings, IPluginSettings<T>, are in LANCommander.SDK.

Subscribe to server events in InitializeAsync and dispose the subscription when the plugin stops:

var events = context.Services.GetRequiredService<IPluginEventBus>();

_subscription = events.Subscribe<PlaySessionStartedEvent>((e, ct) =>
{
    // Runs on the request that started the session: hand slow work off
    return Task.CompletedTask;
});

The events are games created, updated and deleted; archives uploaded; user accounts created, approved and deleted; play sessions started and ended; issues reported and resolved; and game server status changes. Handlers of all but the last run on the request that caused the change and are awaited, so keep them quick. A handler that throws is logged and changes nothing else.

The documentation site has a walkthrough under Plugins.

IGameProvider.GetCustomFieldsAsync() reads custom fields across all games, including their game ids, for bulk provenance checks. IGameVersionProvider can read and replace a version's redistributables and set their per-version option values; keeping a redistributable keeps its options, and creating a new version carries those options forward. GetOrCreateLatestAsync creates an empty initial version only when the game has none, without publishing an existing draft.

IServerProvider.ListFilesAsync(serverId, relativePath, cancellationToken), OpenFileAsync(serverId, relativePath, cancellationToken) and WriteFileAsync(serverId, relativePath, content, cancellationToken) use the host's checked file routing, not a plugin's engine implementation or credentials. An empty list path means the engine's file root: a local working directory or the root configured by an extension (not necessarily its executable directory). Paths must be relative; traversal, absolute paths and malformed names throw. Listing returns ServerFileInfo with Name, root-relative Path (using /), IsDirectory, nullable Size in bytes and nullable UTC LastModified.

Missing servers throw KeyNotFoundException, missing engines throw InvalidOperationException, and engines without file support throw NotSupportedException. Engine failures propagate, including unavailable or stopped containers; they are not empty inventories. Missing folders and files remain DirectoryNotFoundException and FileNotFoundException respectively. The engine is responsible for reporting availability; local files do not require a running game process.

Dispose an opened stream before the plugin service scope ends. It may be nonseekable; use cancellable reads rather than assuming Length or Position are available. Writes read from the content stream's current position and leave it open. Writes replace existing content, create parent folders and are not atomic; cancellation can leave partial content. These trusted host services do not authorize callers: protect plugin pages/endpoints with PluginAccess/endpoint access policies and use a host-created scope for background work.

These file-provider methods are an unreleased addition, not part of published 2.2.0-beta.1. For source validation, pack the SDK, server plugin contracts and server UI with the same explicit local version (for example -p:Version=2.2.0-beta.1-fileaccess.local.1) into a private local feed. Reference that version only for the consumer under development, keeping ExcludeAssets="runtime". An actual host built from the matching source is required; installing compile-time packages does not add the implementation to an existing beta.1 host. Publication and release integration are separate prerequisites.