Skip to content

Using NAME On Non Web Applications

Miguel Alexandre edited this page Jul 4, 2017 · 2 revisions

In order to allow the usage of NAME in non-web applications we created the NAME.SelfHost.HttpListener and NAME.SelfHost.Kestrel NuGet packages which target .Net 4.5 and .Net Standard 1.6 respectively.

These packages provide a way to seamlessly add NAME functionality to projects without a web server, they take care of instantiating a web server listening in the port range 40500-40600 to maintain NAME funcionality, including:

  • 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.

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

Enabling the SelfHost NAME is as easy as calling a method, you only need to decide where the initilization should take place. Usually, in a Console application it should be one of the first things to be executed in the Main method.

The method to start NAME is EnabledName present in the NAMEServer static class. And just like the other packages you configure NAME by passing a configuration lambda as parameter.

You should dispose the value returned by the EnableName method, to ensure the web server is properly closed and disposed.

SelfHostResult selfHostResult = NAMEServer.EnableName(config =>
{
    Assembly a = typeof(Startup).GetTypeInfo().Assembly;
    config.APIName = a.GetName().Name;
    config.APIVersion = a.GetName().Version.ToString();
});

/* 
   ...
   The rest of your application
   ...
*/

selfHostResult.Dispose();

Also, you need to reference the corresponding namespace.

using NAME.SelfHost.HttpListener;
// or
using NAME.SelfHost.Kestrel;

Making Sure It Works

To make sure that NAME was properly installed and enabled, start your application, the endpoint and port of the created web server should be printed in the console output, simply access the 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.
AddressToListenOn "*" The address of the interface where the server will listen for incoming connections, "*" binds to all IPs.
LogHealthCheckToConsole false Wether or not logs should be written to the console output.