Nano.App 10.0.0-preview1

Nano.App

Common features for all types of Nano application.

⚠️ This NuGet is transitive and included in other Nano Packages, and is not meant to be included directly.

Table of Contents

• Home
• Summary
• Environment
• Configuration
  • Null Logger
  • Api Clients
• Start-Up Tasks
• Custom Services
• Custom Middleware
• Custom Configuration Section

Summary

Applications are the core part of Nano.
In Nano, an application refers to the part of defining, building and running a host process.

Conrete application implementations derive from BaseNanoApplication and implements the IApplication interface, following the common Nano application patterns and providing a concrete implementation for building applications with Nano. It provides convenient static methods to create and configure the application with sensible defaults, while allowing full customization of services through the ConfigureServices method. This design ensures that all core applications behaviors are initialized consistently using you configuration, reducing boilerplate code and simplifying the setup of new applications.

Three concrete types application are avaialble in Nano.

Environment

By design, Nano is environment-neutral: it does not rely on environment-specific code or behavior.
Environment-specific behavior is defined solely through configuration files, such as appsettings.{environment}.json.

.NET Core reads the DOTNET_ENVIRONMENT or ASPNETCORE_ENVIRONMENT variable and applies the corresponding configuration. By default, the environment is set to Development.
Generally, it's recommended to keep code environment-neutral and handle differences through configuration and deployment pipelines.

Nano supports three standard environments:

⚠️ Additional environments can easily be added by updating deployment settings and corresponding configuration files.

Configuration

Nano follows the standard .NET Core configuration pattern, loading key/value pairs from configuration providers.
By default, Nano uses appsettings.json, but individual settings can be overridden using environment variables, command-line arguments, or user secrets.

The order of precedence for configuration sources is as follows (later items override earlier ones):

1. App Settings
   1. appsettings.json
   2. appsettings.{environment}.json
2. Command-Line Arguments (args)
3. Environment Variables
4. User Secrets (Development environment only)

Nano handles empty configuration sections, differently than the regular .NET configuration. Empty sections are mapped with all default configuration values, in contrary to setting the whole section to null in the configuration. Another improvements is how Nano handles appsettings.{environment}.json overrides. In regular .NET configuration, setting an entire JSON section to null is ignored. Nano supports this scenario, allowing a section defined in appsettings.json to be set to null in an environment-specific configuration file, effectively overriding and removing that configuration for the environment.

Null Logger

Nano automatically registers a NullLogger, ensuring that ILogger and related logging services are available even if no logging provider has been configured.
With the NullLogger, all log messages are discarded, so no logs are persisted.

This is intended as a safety fallback.

📖 Learn more about Nano Logging Providers.

Api Clients

Nano provides a generic API client implementation that allows other Nano applications to seamlessly connect and communicate with your application over HTTP.

This feature is intended for API-based application types. Console applications do not implement API clients, since they do not expose HTTP endpoints, but they can still consume API clients from other applications. To create an API client, derive from either BaseApiClient or BaseApiClient<TIdentity> and implement the required constructor. If your application uses Nano Identity, you should instead derive from BaseIdentityApiClient<TUser> or BaseIdentityApiClient<TUser, TIdentity>, where TUser represents the IEntityUser model defined in your application and TIdentity represents the identity type.

The base classes provide a structured set of methods for invoking built-in Nano API endpoints. They expose controllers and actions through a generic, convention-based approach, allowing you to call endpoints without manually constructing HTTP requests. This ensures strongly typed communication and consistent integration patterns across Nano applications.

A minimal example of an API client implementation is shown below.

public class MyApiClient(ApiClient apiClient) : BaseApiClient(apiClient)
{
}

or with Identity.

public class MyIdentityApiClient<TUser>(ApiClient apiClient) : BaseIdentityApiClient(apiClient)
{
}

You do not need to implement anything beyond this to get a fully working API client. However, you can continue reading to learn how to extend the client with custom methods, including custom request and response types for your own application-specific endpoints. You can also explore the built-in API client methods for Nano entity models, audit, authentication, and identity.

The application consuming the API client must add a configuration entry in appsettings.json that defines the connection information and behavior. The configuration is structured as a dictionary, allowing multiple API clients for different applications to be registered. Each entry must match the type name of the api-client implementation and must be unique to avoid conflicts.

"App": {
  "Apis": {
    "MyApiClient": {
      "Host": "localhost",
      "Root": "api",
      "Port": 80,
      "UseSsl": false,
      "Timeout": "00:00:30",
      "LogInRoot": {
        "Username": null,
        "Password": null
      }
      "HealthCheck": {
        "UnhealthyStatus": Unhealthy
      }
    }
  }
}

All API client implementations are automatically registered during startup using the options defined in the configuration. They can then be injected and used wherever needed through dependency injection.

The application has access to several groups of endpoints exposed as properties on the BaseApiClient: Entity, Auth, and Audit. Implementations deriving from BaseIdentityApiClient also have access to the Identity group. Each group contains endpoints organized by their respective domain and purpose. Endpoints that are not enabled in the API application via configuration will return a 404 response if invoked. For example, if authentication is disabled and an endpoint from the Auth group is called, the request will result in a 404 response.

The Entity method group in the API client provides generic methods for working with your entity data models through the Entity Controllers in your application. It exposes methods for all standard Nano controller actions, including get, query, add, edit, and delete. The TEntity generic parameter defines the entity type used when invoking a method and also determines the corresponding controller route segment. For example, using MyEntity will target the /MyEntitys/ route, following Nano’s controller naming conventions.

The following entity methods are available. Additional overloads are also provided, but have been omitted here for simplicity.

A dedicated method group is provided for Audit, exposing read-only operations for AuditEntry<TIdentity>.

The following methods are available for Auth operations.

Finally, for API client implementations that support Identity, the following methods are available through the Identity method group.

In addition to the built-in Nano methods, custom API client methods are fully supported. Adding custom methods with dedicated request and response contracts is straightforward and is the recommended way to extend the API client with application-specific functionality.

Start by creating a request type that derives from BaseRequest. Then annotate the class with one of the available ActionAttribute variants shown below. This attribute defines both the HTTP method and the relative route of the endpoint. The configuration must match the corresponding endpoint defined in your application controller.

⚠️ Ensure that the action route is relative and does not start with /.

A simple POST request implementation could you look like this.

[PostAction("custom")]
public class MyCustomRequest : BaseRequest

Next, add properties to the request and annotate them with request data attributes. The table below lists the available Nano attributes, along with their purpose and behavior.

The updated request example below demonstrates how each attribute can be used in practice.

[PostAction("{id}/custom")]
public class MyCustomRequest : BaseRequest
{
    [Header(Name = "CustomHeader", ValuePrefix = "Custom-")]
    public string Header { get; set; }

    [Route(Order = 0)]
    public string Id { get; set; }

    [Query(Name = "MyQuery")]
    public string Query { get; set; }

    [Body]
    public MyBody Body { get; set; }

    [Form]
    public NamedStream File { get; set; }
}

Next, an optional response contract can be defined if the endpoint returns data. The response type can be any concrete class and does not need to inherit from any base type.

public class MyResponse
{
    // Properties
}

For file responses, use either Stream or NamedStream if the filename should be preserved.

Similar to the entity API client methods, the pluralized TResponse type name represents the controller segment of the route. This is the standard convention in Nano and works well in most cases, since custom endpoints typically extend existing entity controllers and return the corresponding entity type, ensuring route consistency. However, when an endpoint does not return a response, or when the route does not align with the TResponse naming convention, the controller route must be explicitly specified in the request, as shown below.

public class MyRequest : BaseRequest
{
    public MyRequest()
    {
        this.Controller = "my-controller-route";
    }
}

Finally, add a method to your API client class that invokes the request using either InvokeAsync<TRequest> for endpoints that do not return a response, or InvokeAsync<TRequest, TResponse> for endpoints that return a typed response, both provided by BaseApiClient. These methods act as the execution layer for your custom API client methods and handle the full request lifecycle, including serialization, routing, and HTTP communication. This keeps your API client methods clean and consistent, while ensuring that all execution logic is centralized in the shared base implementation.

public class MyApiClient(ApiClient apiClient) : BaseApiClient(apiClient)
{
    public Task GetMyResponse(MyRequest request)
    {
        return this.InvokeAsync<MyRequest>(request);
    }

    public Task<MyResponse?> GetMyResponse(MyRequest request)
    {
        return this.InvokeAsync<MyRequest, MyResponse>(request);
    }
}

In addition to request execution, the API client also handles propagation of HTTP context and authentication details to ensure consistent behavior across service boundaries. Accept headers and all X-Forwarded-* headers are automatically transferred from the current HttpContext, if available, and forwarded with the outgoing request. The same applies to the Authorization and X-Api-Key headers, as well as other built-in Nano headers. The set of automatically forwarded headers may evolve over time, but the Nano API client ensures that relevant request metadata from the outer request is propagated to internal requests whenever appropriate.

Authentication is handled internally by the API client implementation to ensure consistent and secure communication between services. By default, the JWT token from the incoming Authorization header is reused and forwarded with outgoing requests. If the target service shares the same issuer, audience, and signing key, this token can be used directly for authorization. If no JWT token is present, Nano will, if configured, automatically authenticate using the root login credentials defined in ApiOptions. The resulting JWT token is stored statically and reused for subsequent requests to avoid unnecessary re-authentication.

It is also possible to explicitly override the JWT token by setting BaseRequest.JwtTokenOverride, allowing full control over the authentication context for individual requests.

Start-Up Tasks

Nano supports running background jobs during application start-up.
A failing startup task that throws an unhandled exception will cause the application to shut down. Startup tasks must complete successfully for the application to run.

Implement startup tasks by deriving from the abstract BaseStartupTask or implementing the IStartupTask interface. Dependencies are automatically registered and executed during application start-up. For convenience, deriving from BaseStartupTask allows you to implement only OnStartAsync() if no custom logic is needed in OnStopAsync().

public class MyStartUpTask(ILogger logger) 
    : BaseStartupTask(logger)
{
    public override async Task OnStartAsync(CancellationToken cancellationToken = default)
    {
        // Your startup logic here...
    }

    // Optional
    public override async Task OnStopAsync(CancellationToken cancellationToken = default)
    {
        // Your shutdown/cleanup logic here...
    }
}

You can inject any registered service your startup task needs, including scoped services, which will be correctly resolved when the startup task is executed.

Custom Services

All Nano application types support registering custom services.
Simply add your services during the ConfigureServices(...) step when building the application in Program.cs.

Each application type’s documentation provides detailed guidance on how to configure and build the application, customize services, and where to place them.

...
    .ConfigureServices(services =>
    {
        // Your services...
    })
...

Custom Middleware

Custom middleware works similarly to custom services.
During the Build(...) step in Program.cs, add your middleware to the IApplicationBuilder delegate parameter.

⚠️ All custom middleware is appended to the end of the middleware pipeline registered by Nano.

...
    .Build(builder =>
    {
        // Your middleware..
    })
...

⚠️ Custom middleware is supported only by API and Web applications. In Console applications, the builder delegate is ignored.

Custom Configuration Section

Extending Nano with custom configuration sections is straightforward and integrates seamlessly with existing Nano configuration.

Use the IServiceCollection extension AddConfigOptions<TOption>(...) to register your custom configuration section. The generic type TOption defines the object model into which the section will be deserialized. You may register as many custom sections as you like, as long as they don't conflict with the built-in sections in Nano, App, Logging, Data, Eventing, and Storage.

To add a custom configuration section, first define an options model that represents the structure of your configuration section.

public class MySectionModel
{
    // Properties...
}

Next, Add a matching section to appsetings.json.

{
    "MySection": {
    }
}

Last, register the section as options.

.ConfigureServices(services =>
{
    services
        .AddNanoConfigSection<MySectionModel>("MySection", out var options);
})

The options are returned for use in further service registration, and it is now also available for dependency injection through the IOptions<T> and related interfaces.