Microsoft.WindowsAdminCenter.FeatureExternal 2.1.0

SDK interface

The SDK package allows to use the following public interfaces.

• IFeatureControllerStartup - The controller can leverage Dependency Injection (DI) and Middleware capability to share common services among various points. Defines a class based on the interface to get starting.

/// <summary>
/// The interface of startup operations for feature controller.
/// </summary>
public interface IFeatureControllerStartup
{
    /// <summary>
    /// Gets the ordering preference of middleware registration.
    /// </summary>
    public ApplicationConfigurationOrderingPreference ApplicationConfigurationOrderingPreference;

    /// <summary>
    /// Partially configures the service objects for the feature controller. Final set of services will include system
    /// services and other feature controllers.
    /// </summary>
    /// <param name="configuration">The configuration object from appsettings.json on the service.</param>
    /// <param name="services">The collection of services.</param>
    public void PartiallyConfigureServices(IConfiguration configuration, IServiceCollection services);

    /// <summary>
    /// Partially configure Web Application for the feature controller. Final configuration of web application includes
    /// system and other feature controller's settings.
    /// </summary>
    /// <param name="configuration">The configuration object from appsettings.json on the service.</param>
    /// <param name="app">The application builder.</param>
    public void PartiallyConfigureApplication(IConfiguration configuration, IApplicationBuilder app);
}

• HttpContextExtensions - On HttpContext, using extension methods the controller can access node's security context.

public static class HttpContextExtensions
{
    /// <summary>
    /// Gets the username on current context.
    /// </summary>
    /// <param name="context">The HTTP context object.</param>
    /// <returns>The username.</returns>
    public static string Username(this HttpContext context);

    /// <summary>
    /// Gets current feature identity context from HttpContext.
    /// </summary>
    /// <param name="context">The HTTP context object.</param>
    /// <returns>The username.</returns>
    public static IFeatureIdentityContext FeatureIdentityContext(this HttpContext context);
}

• IFeatureIdentityContext provides access mechanism to security context.

/// <summary>
/// The interface of identity context.
/// </summary>
public interface IFeatureIdentityContext
{
    /// <summary>
    /// Gets the Windows identity of request.
    /// </summary>
    ClaimsIdentity WindowsIdentity { get; }

    /// <summary>
    /// Gets network credentials from AuthHeader.
    /// </summary>
    /// <param name="nodeName">The node name.</param>
    /// <returns>the network credentials.</returns>
    NetworkCredential GetNetworkCredential(string nodeName);

    /// <summary>
    /// Impersonate on logon user or Auth header user.
    /// </summary>
    /// <param name="node">The node name. if node is null, it indicates a remote node.</param>
    /// <param name="action">The action.</param>
    void RunImpersonated(string node, Action action);

    /// <summary>
    /// Impersonate on logon user or Auth header user.
    /// </summary>
    /// <param name="node">The node name. if node is null, it indicates a remote node.</param>
    /// <param name="action">The action.</param>
    /// <returns>the async task object.</returns>
    Task RunImpersonatedAsync(string node, Func<Task> action);

    /// <summary>
    /// Try get credentials from auth header or the cluster node.
    /// </summary>
    /// <param name="nodeName">The node name.</param>
    /// <param name="credentials">Output the credentials, otherwise it's null.</param>
    /// <returns>True if it could get the credentials.</returns>
    bool TryGetCredentials(string nodeName, out Tuple<string, string, SecureString> credentials);
}

• IFeatureLogger provides an interface for logging. Internally, the implementation of this interface uses our Logger class, which is instantiated in Startup.cs. So, IFeatureLogger cannot be used before Startup.cs runs.

/// <summary>
/// The interface of logger for feature controller.
/// </summary>
public interface IFeatureLogger
{
    /// <summary>
    /// Log critical message.
    /// </summary>
    /// <param name="message">The message.</param>
    /// <param name="args">The arguments.</param>
    public void LogCritical(string message, params object?[] args);

    /// <summary>
    /// Log critical exception.
    /// </summary>
    /// <param name="exception">The exception.</param>
    /// <param name="message">The message.</param>
    /// <param name="args">The arguments.</param>
    public void LogCritical(Exception exception, string? message, params object?[] args);

    /// <summary>
    /// Log error message.
    /// </summary>
    /// <param name="message">The message.</param>
    /// <param name="args">The arguments.</param>
    public void LogError(string message, params object?[] args);

    /// <summary>
    /// Log error exception.
    /// </summary>
    /// <param name="exception">The exception.</param>
    /// <param name="message">The message.</param>
    /// <param name="args">The arguments.</param>
    public void LogError(Exception exception, string? message, params object?[] args);

    /// <summary>
    /// Log warning message.
    /// </summary>
    /// <param name="message">The message.</param>
    /// <param name="args">The arguments.</param>
    public void LogWarning(string message, params object?[] args);

    /// <summary>
    /// Log warning exception.
    /// </summary>
    /// <param name="exception">The exception.</param>
    /// <param name="message">The message.</param>
    /// <param name="args">The arguments.</param>
    public void LogWarning(Exception exception, string? message, params object?[] args);

    /// <summary>
    /// Log information message.
    /// </summary>
    /// <param name="message">The message.</param>
    /// <param name="args">The arguments.</param>
    public void LogInformation(string message, params object?[] args);

    /// <summary>
    /// Log information exception.
    /// </summary>
    /// <param name="exception">The exception.</param>
    /// <param name="message">The message.</param>
    /// <param name="args">The arguments.</param>
    public void LogInformation(Exception exception, string? message, params object?[] args);

    /// <summary>
    /// Log trace message.
    /// </summary>
    /// <param name="message">The message.</param>
    /// <param name="args">The arguments.</param>
    public void LogTrace(string message, params object?[] args);

    /// <summary>
    /// Log trace exception.
    /// </summary>
    /// <param name="exception">The exception.</param>
    /// <param name="message">The message.</param>
    /// <param name="args">The arguments.</param>
    public void LogTrace(Exception exception, string? message, params object?[] args);

    /// <summary>
    /// Log debug message.
    /// </summary>
    /// <param name="message">The message.</param>
    /// <param name="args">The arguments.</param>
    public void LogDebug(string message, params object?[] args);

    /// <summary>
    /// Log debug exception.
    /// </summary>
    /// <param name="exception">The exception.</param>
    /// <param name="message">The message.</param>
    /// <param name="args">The arguments.</param>
    public void LogDebug(Exception exception, string? message, params object?[] args);
}