Using NAME On Web Applications - nosinovacao/name-sdk GitHub Wiki

In order to provide a more pleasing and faster experience for the developer, we created the NAME.WebApi and NAME.AspNetCore NuGet packages which allows the developer to seamlessly add NAME to an existing WebApi or AspNetCore project respectively.

These packages take care of performing the five key features of NAME:

  • Perform an application start diagnostic check - When the application starts, NAME will read your dependencies file and check all your dependencies for valid versions and connectivity.
  • Provide a /manifest endpoint - A route for the endpoint GET/manifest will be created which serves the manifest in JSON format.
  • Provide a /manifest/ui endpoint - A route for the endpoint GET /manifest/ui will be created which serves an HTML page containing mechanisms to show the dependencies in a user-friendly table format.
  • Start a routine to try to register in a central registration service.
  • In case of the NAME.WebApi package, adds an IIS Http Module for the name endpoint header, which adds the X-NAME-Manifest-Endpoint header to ALL responses of the WebApi. The AspNetCore package does this through the middleware.

Installation

To install all you need to do is add the NuGet package corresponding to your project type.

Adding Dependencies

After installing the package, create a dependencies.json in the root folder of your project. Change this file with the dependencies of the application.

Refer to the Dependencies File document for instructions on how to use this file.

Enabling NAME

NAME.WebApi

After installing the package, a NAMEConfig.cs file will be in the App_Start folder of your project, by default it enables NAME. This file allows you to configure some of the NAME behaviour.

NAME.AspNetCore

To enable NAME on ASP.Net Core you need to add the middleware to the pipeline to the Configure method of your Startup.cs file, make sure the NAME middleware is registered first so that the custom header is set betfore any other middleware has a chance to send a response.

app.UseNAME(config =>
{
    Assembly a = typeof(Startup).GetTypeInfo().Assembly;
    config.APIName = a.GetName().Name;
    config.APIVersion = a.GetName().Version.ToString();
});

Make sure you also include the NAME.AspNetCore namespace.

using NAME.AspNetCore;

Making Sure It Works

To make sure that NAME was properly installed and enabled, start your application and access the /manifest endpoint. The response should be your manifest, with the versions of the dependencies you configured. You can also access the /manifest/ui endpoint to make sure the table UI is working.

Configuration Options

The following configuration options are available:

Property Default Value Description
ManifestUriPrefix "" Prefix for the /manifest and /manifest/ui endpoint. For example, if this is set to "api/v1", the endpoints will be api/v1/manifest and api/v1/manifest/ui.
DependenciesFilePath "~/dependencies.json" The path for the dependencies file. For local files, the path should start with "~/".
APIName Name of the project assembly The name of the API, this will be in the returned manifest and is merely informative.
APIVersion Version of the project assembly The version of the API, this will be in the returned manifest.
ThrowOnDependenciesFail false Whether or not the application start diagnostic check should cause the application start to fail. This is useful in a critical scenario where the application should NEVER start if the dependencies fail.