Table of Contents

Class AppHost<TApp>

Namespace
RDCore.SDK.Server
Assembly
RDCore.SDK.dll

A RDCore.SDK application host.

public abstract class AppHost<TApp> : IDisposable where TApp : class, IRDCoreApp

Type Parameters

TApp

The type of IRDCoreApp being hosted.

Inheritance
AppHost<TApp>
Implements
Derived
Inherited Members

Remarks

👉 This class is inherited by both RDCorePlatformServerHost<TApp> and RDCoreLanguageClientHost<TApp> to encapsulate a common interface to simplify implementing any kind of SDK application.

Constructors

AppHost()

A RDCore.SDK application host.

protected AppHost()

Remarks

👉 This class is inherited by both RDCorePlatformServerHost<TApp> and RDCoreLanguageClientHost<TApp> to encapsulate a common interface to simplify implementing any kind of SDK application.

Fields

ProcessTokenSource

protected readonly CancellationTokenSource ProcessTokenSource

Field Value

CancellationTokenSource

Properties

ExitCode

Gets the application's exit code.

public virtual int ExitCode { get; }

Property Value

int

HostServices

The built host's service provider, or null before BuildAndRunAsync(HostApplicationBuilder, string[]) has built the host.

protected IServiceProvider? HostServices { get; }

Property Value

IServiceProvider

Info

Gets the AssemblyName of this application.

public static AssemblyName Info { get; }

Property Value

AssemblyName

Remarks

👉 Its numeric Version is the one workspace (.rdproj) versions are stamped with and that the language server's WorkspaceService.LoadAsync compares them against; the loader re-stamps a loaded project with it (see the ProjectFile copy constructor), so that check currently compares the running version with itself.
👉 The version reported in ServerInfo and ClientInfo is AssemblyDisplayVersion's.

LogFileName

The name of the file the application logs to, in the platform's logs directory (LogsDirectory), at every level the live log level lets through; null for no file.

protected virtual string? LogFileName { get; }

Property Value

string

Remarks

🧩 The base implementation is null: a client logs where its user sees it. A server's log is its file, which the server host gives every server role by default, so that no role is left without one.

Settings

The settings the application is configured with: what the settings a user set are checked against before the application reads them (AddUserSettings(IConfigurationBuilder, string, SettingsSchema, bool)).

protected virtual SettingsSchema Settings { get; }

Property Value

SettingsSchema

Remarks

🧩 The base implementation is the platform's settings (Platform); an application that binds settings of its own combines its schema with them.

WritesToConsole

Whether the application writes to its console: its log, and what it says as it fails.

protected virtual bool WritesToConsole { get; }

Property Value

bool

Remarks

🧩 The base implementation is true: a client's console is the user's. A server's is no one's to read. A server talks to its client over a pipe and keeps its log in a file, and the process that starts it may redirect its standard output and never read it. A pipe nobody reads fills, and a console logger then blocks every thread that logs. A server answers false: it logs nothing to its console, and what it has to say as it fails goes to its standard error.

Methods

AfterAppRunAsync(IServiceProvider)

🧩 A method that runs after RunAsync(IServiceProvider, string[]) returns, but before the host is stopped.
Base implementation returns a CompletedTask.

protected virtual Task AfterAppRunAsync(IServiceProvider provider)

Parameters

provider IServiceProvider

The constructed service provider.

Returns

Task

Remarks

👉 A server app blocks inside RunAsync until its LSP server exits, so the base no-op is correct for it.
👉 A standalone LSP client process (e.g. rdc.exe) returns from RunAsync as soon as the JSON-RPC connection is established; it overrides this method to keep the process alive for the lifetime of that connection.

BeforeAppStartAsync(IServiceProvider)

🧩 A method that runs after configuration but before the application is resolved and actually started.
Base implementation returns a CompletedTask

protected virtual Task BeforeAppStartAsync(IServiceProvider provider)

Parameters

provider IServiceProvider

The constructed service provider.

Returns

Task

BuildAndRunAsync(HostApplicationBuilder, string[])

Builds the host, resolves and runs the TApp application.

protected virtual Task BuildAndRunAsync(HostApplicationBuilder builder, string[] args)

Parameters

builder HostApplicationBuilder
args string[]

Returns

Task

Remarks

Overrides should invoke the base implementation to run the base protocol.

Configure(IConfigurationBuilder, IServiceCollection, string[])

Override to supply application-specific IConfiguration configuration.

protected abstract void Configure(IConfigurationBuilder configuration, IServiceCollection services, string[] args)

Parameters

configuration IConfigurationBuilder

An IConfigurationBuilder to configure application settings.

services IServiceCollection

The services of the application host being built, to register the application's own services in.

args string[]

Any command-line arguments that were supplied to the application, parsed into SdkAppOptions.

Remarks

🧩 The base implementation binds and configures appsettings.json options, with command-line arguments as overrides.

ConfigureAdditionalExternalServices(IServiceCollection, IConfiguration)

Configures any additional services that must be injected in the application constructor.
🧩 The base implementation does nothing.

protected virtual void ConfigureAdditionalExternalServices(IServiceCollection services, IConfiguration configuration)

Parameters

services IServiceCollection

The service provider of the application host being configured.

configuration IConfiguration

The current application configuration.

Remarks

👉 The purpose of external services is to bootstrap the application and support functionality at the entry point level by registering the services that must be injected in the IRDCoreApp application.

ConfigureExternalLogging(IServiceCollection, ILoggingBuilder, IConfiguration)

Configures the external service provider logging targets for a RDCore.SDK client/server application.

protected virtual void ConfigureExternalLogging(IServiceCollection services, ILoggingBuilder builder, IConfiguration configuration)

Parameters

services IServiceCollection

The service provider of the application host being configured.

builder ILoggingBuilder

The ILoggingBuilder to configure logging providers.

configuration IConfiguration

The current application configuration.

Remarks

👉 The external services are not registered with the OmniSharp language server host.
Their purpose is to bootstrap the application and support functionality at the entry point level by registering the services that must be injected in the IRDCoreApp application.

🧩 The default/base implementation:

  • Sets the effective minimum log level as per the supplied TraceLevel.
  • Adds a Debug logger in debug builds.

Whatever an override does, the application's file log (LogFileName) is added before it, and an application that does not write to its console (WritesToConsole) has the generic host's console logger removed after it.

ConfigureExternalServices(IServiceCollection, IConfiguration)

Configures only the services needed to resolve the IRDCoreApp instance.

protected virtual void ConfigureExternalServices(IServiceCollection services, IConfiguration configuration)

Parameters

services IServiceCollection

The service provider of the application host being configured.

configuration IConfiguration

The current application configuration.

Remarks

🧩 If you don't intend to overwrite the core service registrations, you probably want to override ConfigureAdditionalExternalServices(IServiceCollection, IConfiguration) instead.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Dispose(bool)

The standard .NET Dispose Pattern. Override to cleanly dispose of any instance-level IDisposable references.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

Remarks

⚠️ Overrides MUST invoke the base.Dispose(bool) base implementation.

LogIfEnabled(LogLevel, string)

public void LogIfEnabled(LogLevel logLevel, string message)

Parameters

logLevel LogLevel
message string

ResolveTraceLevel(IConfiguration)

The minimum log level a component starts with — TraceLevel from configuration, or Information when it is unset or invalid. It is a live setting (RDCore.SDK.Server.Logging.LiveLogLevel): a provider added in a ConfigureExternalLogging(IServiceCollection, ILoggingBuilder, IConfiguration) override is added with Trace - the bare AddFile(path) pins the file at Information and hides JSON-RPC protocol tracing - and the base implementation's filter decides.

protected static LogLevel ResolveTraceLevel(IConfiguration configuration)

Parameters

configuration IConfiguration

Returns

LogLevel

RunAsync(string[])

Runs the RDCore.SDK client/server application.

public Task<int> RunAsync(string[] args)

Parameters

args string[]

Returns

Task<int>

Remarks

RDCore.SDK plugins should await this method inside a try...catch block in the application's entry point (Program.cs) to block execution until the internal Omnisharp LSPserver exits.

Exceptions

OperationCanceledException

Signals a normal exit; host application process should exit with code 0.

Exception

Any other exception type is unexpected and if it is fatal, the host application process should exit with a non-zero error code.

ShowSplash(IServiceProvider, IReadOnlyList<string>)

🧩 Shows the application's splash as it starts. Override it to show a splash of your own, or none.

protected virtual void ShowSplash(IServiceProvider provider, IReadOnlyList<string> args)

Parameters

provider IServiceProvider

The application's services, as BeforeAppStartAsync(IServiceProvider) left them.

args IReadOnlyList<string>

The command line the application was started with.

Examples

The platform's splash with a title of the application's own, in plain text:

protected override void ShowSplash(IServiceProvider provider, IReadOnlyList<string> args)
    => PlatformSplash.WriteTo(Console.Out, title: new SplashTitle(["M Y   A P P"], LogoIndent: 0));

Each line styled by its part, as a console with colours draws it:

protected override void ShowSplash(IServiceProvider provider, IReadOnlyList<string> args)
{
    foreach (var line in PlatformSplash.Lines(title: new SplashTitle(["M Y   A P P"], LogoIndent: 0)))
    {
        Console.ForegroundColor = line.Part == SplashPart.Title ? ConsoleColor.White : ConsoleColor.Yellow;
        Console.WriteLine(line.Text);
    }
    Console.ResetColor();
}

No splash:

protected override void ShowSplash(IServiceProvider provider, IReadOnlyList<string> args) { }

Remarks

When it runs. Once per run of the application: after BeforeAppStartAsync(IServiceProvider), so that what the application set up there (its theme, its console) is ready to draw with, and before the application runs, so that the splash comes before anything the application writes. It does not run for a command line the application answers without starting (TryAnswerCommandLine(string[], out int): --help, --version), nor when the application fails before it is built.

What the base implementation draws. The platform's splash (PlatformSplash): the logo, the slogan, the version line and the copyright notice, in the language of the user interface, as plain text (WriteTo(TextWriter, CultureInfo?, SplashTitle?)). It writes it to the standard output of an application that writes to its console (WritesToConsole), and only when that output is a console: output redirected to a file or a pipe is a program's, and gets no splash in it. A server never shows one.

Your own splash. An override replaces the base implementation: what it draws is the one splash the application shows, and the platform's plain one is not drawn as well. To draw with:

No splash. An override that draws nothing shows no splash at all. It can also draw nothing for some command lines only, and call the base implementation for the others: for a command whose output is the splash itself, say.

TryAnswerCommandLine(string[], out int)

🧩 Answers a command line that is not to be run with, before any of the host exists.

public virtual bool TryAnswerCommandLine(string[] args, out int exitCode)

Parameters

args string[]

The command-line arguments as received.

exitCode int

The process exit code, when this returns true. The base implementation answers 0 for a help or version request, and -1 for a command line that cannot be parsed.

Returns

bool

true if the command line has been answered: the caller does not run the host, and RunAsync(string[]) returns exitCode. false if the caller goes on to run it.

Remarks

The base implementation reads args as the platform's command line (SdkAppCommandLineArgs), which is what a client or a server application is started with, and answers a request for help or version text and a command line it cannot make sense of.

👉 An application whose arguments are not the platform's (a command-line tool that takes a verb and the verb's own options) overrides this and answers false: every option of the verb is one the platform's parser has never heard of, and would be rejected as a mistake before the verb was ever reached. What is wrong with such a command line is for the verb to say.

An override that answers a command line builds and starts nothing.

RunAsync(string[]) calls this first, and so may an entry point that answers a command line before it builds anything.