Class AppHost<TApp>
A RDCore.SDK application host.
public abstract class AppHost<TApp> : IDisposable where TApp : class, IRDCoreApp
Type Parameters
TAppThe type of IRDCoreApp being hosted.
- Inheritance
-
AppHost<TApp>
- Implements
- Derived
-
RDCoreLanguageClientHost<TApp>RDCorePlatformServerHost<TApp>
- 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
Properties
ExitCode
Gets the application's exit code.
public virtual int ExitCode { get; }
Property Value
HostServices
The built host's service provider, or null before BuildAndRunAsync(HostApplicationBuilder, string[]) has built the host.
protected IServiceProvider? HostServices { get; }
Property Value
Info
Gets the AssemblyName of this application.
public static AssemblyName Info { get; }
Property Value
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
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
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
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
providerIServiceProviderThe constructed service provider.
Returns
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
providerIServiceProviderThe constructed service provider.
Returns
BuildAndRunAsync(HostApplicationBuilder, string[])
Builds the host, resolves and runs the TApp application.
protected virtual Task BuildAndRunAsync(HostApplicationBuilder builder, string[] args)
Parameters
builderHostApplicationBuilderargsstring[]
Returns
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
configurationIConfigurationBuilderAn IConfigurationBuilder to configure application settings.
servicesIServiceCollectionThe services of the application host being built, to register the application's own services in.
argsstring[]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
servicesIServiceCollectionThe service provider of the application host being configured.
configurationIConfigurationThe 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
servicesIServiceCollectionThe service provider of the application host being configured.
builderILoggingBuilderThe ILoggingBuilder to configure logging providers.
configurationIConfigurationThe 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
Debuglogger 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
servicesIServiceCollectionThe service provider of the application host being configured.
configurationIConfigurationThe 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
disposingbool
Remarks
⚠️ Overrides MUST invoke the base.Dispose(bool) base implementation.
LogIfEnabled(LogLevel, string)
public void LogIfEnabled(LogLevel logLevel, string message)
Parameters
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
configurationIConfiguration
Returns
RunAsync(string[])
Runs the RDCore.SDK client/server application.
public Task<int> RunAsync(string[] args)
Parameters
argsstring[]
Returns
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
providerIServiceProviderThe application's services, as BeforeAppStartAsync(IServiceProvider) left them.
argsIReadOnlyList<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:
provider: the application's services, the ones its console and its theme are among.- Lines(CultureInfo?, SplashTitle?): the platform's splash, line by line, each line with the part of the splash it is of (SplashPart), to style as your console does.
- SplashTitle: a title of your own, which Lines(CultureInfo?, SplashTitle?) puts between the logo and the slogan and centres the slogan under.
- WriteTo(TextWriter, CultureInfo?, SplashTitle?): the same lines, written as plain text.
args: the command line, for a splash that depends on what the application was asked to do.
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
argsstring[]The command-line arguments as received.
exitCodeintThe process exit code, when this returns true. The base implementation answers
0for a help or version request, and-1for 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.