Mapzania.Services Class

The Mapzania.Services class is the primary entry point for setting up and configuring Mapzania .NET services. It is a static class and accessed using the methods listed below.

Static Methods

RegisterLogger

This method allows the user to add a logger to Mapzania for a preferred logging platform (e.g. NLog or log4net).

NOTE: This method can be called multiple times, should you want to register more than one logger class.

Mapzania generates a number of logs namely:

• Error Log - Exceptions are logged to this log
• Debug Log - Detailed debugging information is logged to this log
• Message Log - Messages relating to service events are logged to this log
• Custom Logs - A number of custom events are logged to these logs. These include events such as WebApi calls, Metrics and Usage.

NOTE: See Adding Logging Services for an example of a logger implementation.

Parameters

Name	Required	Type	Description
logger	Yes	Mapzania.Logging.ILogger	The concrete implementation of a logger created by the user.

Example

public class MvcApplication : System.Web.HttpApplication
{
    protected void Application_Start()
    {
        var logPath = @"c:\logs";
        var logger = new NLogLogger(logPath);
        Mapzania.Services.RegisterLogger(logger);

        var logger2 = new Log4NetLogger();
        Mapzania.Services.RegisterLogger(logger2);
    
        Mapzania.Services.Start(this);
    
        AreaRegistration.RegisterAllAreas();
    
        GlobalConfiguration.Configure(WebApiConfig.Register);
    
        RouteConfig.RegisterRoutes(RouteTable.Routes);
        BundleConfig.RegisterBundles(BundleTable.Bundles);
    }
}

RegisterMapboxLayerSource

This method is used to register a single Mapbox layer-source.

To use Mapbox tile-sets as background layers-sources, you need to create an account on the Mapbox website. You will then have access to all the standard Mapbox tile-sets in addition to having the ability to create your own tilesets.

NOTE: Please note that it is your responsibility to comply with all licensing and legal issues relating to Mapbox.

Parameters

Name	Required	Type	Description
key	Yes	String	This is the layer-source key that will be used to identify the Mapbox layer.
options	Yes	Mapzania.Platform.Mapbox.LayerSourceOptions	Options for registering the layer-source (see below for more details).

Options

Name	Default	Required	Type	Description
MapId	null	Yes	String	The Mapbox Map Id for example 'mapbox.satellite'.
AccessToken	null	Yes	String	The Mapbox Access Token that is provided to you when you register on their site.

Example

void Application_Start(object sender, EventArgs e)
{
	...

    // Set options for the Mapbox layer-source
    var options = new Platform.Mapbox.LayerSourceOptions {
        MapId = "mapbox.satellite",
        AccessToken = "[Your Mapbox Access Token]"
    }
    
    // Register the Mapbox layer-source
    Mapzania.Services.RegisterMapboxLayerSource("MAPBOX_SATELLITE", options);
    
    // Start Mapzania
    Mapzania.Services.Start(this);
    
    AreaRegistration.RegisterAllAreas();
    GlobalConfiguration.Configure(WebApiConfig.Register);
    RouteConfig.RegisterRoutes(RouteTable.Routes);
    BundleConfig.RegisterBundles(BundleTable.Bundles);
    ...
}

RegisterMsSqlSpatialDatabase

This method is used to register all spatial tables in an MSSQL Spatial database as layer-sources.

Parameters

Name	Required	Type	Description
connectionString	Yes	String	The connection-string to the database
options	No	Mapzania.Platform.MsSqlSpatial.ProviderOptions	Options for registering the database.

Options

Name	Default	Type	Description
Prefix	String.Empty	String	This string is appended to the spatial table name to provide the layer-source key (which is always uppercase). For example if the spatial table in the database is named "AmericanRivers" and the prefix is set to "USA_" the layer-source key will be "USA_AMERICARIVERS"
DefaultSRID	"LATLONG"	String	Sets the SRID of all layer-sources registered from the database
DefaultIdColumnName	"Id"	String	Sets the id column name for all layer-sources registered from the database
DefaultGeometryColumnName	"Geometry"	String	Sets the geometry column name for all layer-sources registered from the database

Example

void Application_Start(object sender, EventArgs e)
{
	...

    // Obtain a connectionstring from ConfigurationManager (web.config)
    var connectionString = ConfigurationManager.ConnectionStrings["MY_CONNECTION"].ConnectionString;
    
    // Set options for MSSQL Spatial LayerSources
    var options = new Platform.MsSqlSpatial.ProviderOptions {
        Prefix = "MYDB_",
        DefaultSRID = "EPSG:4283",
        DefaultIdColumnName = "MY_ID",
        DefaultGeometryColumnName = "MY_GEOMETRY"
    };
    
    // Register the MSSQl Spatial database
    Mapzania.Services.RegisterMsSqlSpatialDatabase(connectionString, options);
    
    // Start Mapzania
    Mapzania.Services.Start(this);
    
    AreaRegistration.RegisterAllAreas();
    GlobalConfiguration.Configure(WebApiConfig.Register);
    RouteConfig.RegisterRoutes(RouteTable.Routes);
    BundleConfig.RegisterBundles(BundleTable.Bundles);
    ...
}

RegisterPostGISDatabase

This method is used to register all spatial tables in an PostGIS database as layer-sources.

Parameters

Name	Required	Type	Description
connectionString	Yes	String	The connection-string to the database
options	No	Mapzania.Platform.PostGIS.ProviderOptions	Options for registering the database.

Options

Name	Default	Type	Description
Prefix	String.Empty	String	This string is appended to the spatial table name to provide the layer-source key (which is always uppercase). For example if the spatial table in the database is named "AmericanRivers" and the prefix is set to "USA_" the layer-source key will be "USA_AMERICARIVERS"
DefaultSRID	"LATLONG"	String	Sets the SRID of all layer-sources registered from the database

Example

void Application_Start(object sender, EventArgs e)
{
	...

    // Obtain a connectionstring from ConfigurationManager (web.config)
    var connectionString = ConfigurationManager.ConnectionStrings["MY_CONNECTION"].ConnectionString;
    
    // Set options for PostGISl LayerSources
    var options = new Platform.PosGIS.ProviderOptions {
        Prefix = "MYDB_",
        DefaultSRID = "EPSG:4283"
    };
    
    // Register the PostGIS database
    Mapzania.Services.RegisterPostGisDatabase(connectionString, options);
    
    // Start Mapzania
    Mapzania.Services.Start(this);
    
    AreaRegistration.RegisterAllAreas();
    GlobalConfiguration.Configure(WebApiConfig.Register);
    RouteConfig.RegisterRoutes(RouteTable.Routes);
    BundleConfig.RegisterBundles(BundleTable.Bundles);
    ...
}

RegisterRoutes

The purpose of this method is to register the WebApi routes of the REST API and its controllers with your application. These endpoints are used by the JavaScript API for map interactions.

NOTE: This method must be called to activate Mapzania properly. Also, it is vital that you place this line after config.MapHttpAttributeRoutes() and before you define your default route with config.Routes.MapHttpRoute, otherwise the Mapzania endpoints may not initialize correctly.

Parameters

Name	Required	Type	Description
config	Yes	System.Web.Http.HttpConfiguration	The configuration object of the web server instance.
options	No	Mapzania.RouteOptions	Options for route registration.

Options

Name	Default	Type	Description
ApiRootUrl	"mz"	String	This will set the root URL for the Mapzania REST API to a custom URL.

Examples

MVC Only

global.asax

protected void Application_Start()
{
    // Start Mapzania
	Mapzania.Services.Start(this);

    AreaRegistration.RegisterAllAreas();
    FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);

    //Register Mapzania Routes (endpoints)
    Mapzania.Services.RegisterRoutes(GlobalConfiguration.Configuration, new RouteOptions {
        ApiRootUrl="api/mapzania/1.0/"
    });

    RouteConfig.RegisterRoutes(RouteTable.Routes);
    BundleConfig.RegisterBundles(BundleTable.Bundles);
}

WebApi

WebApiConfig.cs (or equivalent)

public static void Register(HttpConfiguration config)
{
	config.MapHttpAttributeRoutes();

    //Register Mapzania Routes (endpoints)
    Mapzania.Services.RegisterRoutes(config, new RouteOptions {
        ApiRootUrl="map_api/1.0/"
    });

    config.Routes.MapHttpRoute(
        name: "DefaultApi",
        routeTemplate: "api/{controller}/{id}",
        defaults: new { id = RouteParameter.Optional }
    );
}

RegisterTomTomMapLayerSource

This method is used to register a single TomTom Online Map layer-source.

To use TomTom layers as background layers-sources, you need to create an account on the TomTom Developer Site.

NOTE: Please note that it is your responsibility to comply with all licensing and legal issues relating to TomTom.

Parameters

Name	Required	Type	Description
key	Yes	String	This is the layer-source key that will be used to identify the TomTom layer.
options	Yes	Mapzania.Platform.TomTom.MapLayerSourceOptions	Options for registering the layer-source (see below for more details).

Options

The options in the table below are described in more detail in the TomTom Online Maps documentation.

Name	Default	Required	Type	Description
ApiKey	null	Yes	String	The API Key provided to you when you register with TomTom.
Layer	LayerEnum.Basic	No	LayerEnum	The layer of the tiles to be rendered.
Style	StyleEnum.Main	No	StyleEnum	The style of the tiles to be rendered.
View	ViewEnum.Unified	No	ViewEnum	The Geopolitical view of the tiles.
Language	"NGT"	No	String	The language to be used in tile labels.

Example

void Application_Start(object sender, EventArgs e)
{
	...

    // Set options for the TomTom layer-source
    var options = new Platform.TomTom.MapLayerSourceOptions {
        ApiKey = "[Your TomTom API Key]",
        Layer = Platform.TomTom.MapLayerSourceOptions.LayerEnum.Basic,
        Style = Platform.TomTom.MapLayerSourceOptions.StyleEnum.Night,
        View = "NGT",
        Language = "fr-FR"        
    }
    
    // Register the TomTom layer-source
    Mapzania.Services.RegisterTomTomMapLayerSource("TOMTOM_TILES_NIGHT", options);
    
    // Start Mapzania
    Mapzania.Services.Start(this);
    
    AreaRegistration.RegisterAllAreas();
    GlobalConfiguration.Configure(WebApiConfig.Register);
    RouteConfig.RegisterRoutes(RouteTable.Routes);
    BundleConfig.RegisterBundles(BundleTable.Bundles);
    ...
}

RegisterTomTomTrafficFlowLayerSource

This method is used to register a single TomTom Online Traffic traffic-flow layer-source.

To use TomTom layers as background layers-sources, you need to create an account on the TomTom Developer Site.

NOTE: Please note that it is your responsibility to comply with all licensing and legal issues relating to TomTom.

Parameters

Name	Required	Type	Description
key	Yes	String	This is the layer-source key that will be used to identify the TomTom layer.
options	Yes	Mapzania.Platform.TomTom.TrafficFlowLayerSourceOptions	Options for registering the layer-source (see below for more details).

Options

The options in the table below are described in more detail in the TomTom Online Traffic Flow documentation.

Name	Default	Required	Type	Description
ApiKey	null	Yes	String	The API Key provided to you when you register with TomTom.
Style	StyleEnum.Absolute	No	StyleEnum	The style of the tiles to be rendered.
Thickness	10	No	Integer32	The thickness of the traffic flows (1-20).

Example

void Application_Start(object sender, EventArgs e)
{
	...

    // Set options for the TomTom layer-source
    var options = new Platform.TomTom.TrafficFlowLayerSourceOptions {
        ApiKey = "[Your TomTom API Key]",
        Style = Platform.TomTom.TrafficFlowLayerSourceOptions.StyleEnum.Absolute,
        Thickness = 15
    }
    
    // Register the TomTom layer-source
    Mapzania.Services.RegisterTomTomTrafficFlowLayerSource("TOMTOM_FLOWS", options);
    
    // Start Mapzania
    Mapzania.Services.Start(this);
    
    AreaRegistration.RegisterAllAreas();
    GlobalConfiguration.Configure(WebApiConfig.Register);
    RouteConfig.RegisterRoutes(RouteTable.Routes);
    BundleConfig.RegisterBundles(BundleTable.Bundles);
    ...
}

RegisterTomTomTrafficIncidentsLayerSource

This method is used to register a single TomTom Online Traffic traffic-incidents layer-source.

To use TomTom layers as background layers-sources, you need to create an account on the TomTom Developer Site.

NOTE: Please note that it is your responsibility to comply with all licensing and legal issues relating to TomTom.

Parameters

Name	Required	Type	Description
key	Yes	String	This is the layer-source key that will be used to identify the TomTom layer.
options	Yes	Mapzania.Platform.TomTom.TrafficIncidentsLayerSourceOptions	Options for registering the layer-source (see below for more details).

Options

The options in the table below are described in more detail in the TomTom Online Traffic Incidents documentation.

Name	Default	Required	Type	Description
ApiKey	null	Yes	String	The API Key provided to you when you register with TomTom.
Style	StyleEnum.S1	No	StyleEnum	The style of the tiles to be rendered.

Example

void Application_Start(object sender, EventArgs e)
{
	...

    // Set options for the TomTom layer-source
    var options = new Platform.TomTom.TrafficIncidentsLayerSourceOptions {
        ApiKey = "[Your TomTom API Key]",
        Style = Platform.TomTom.TrafficIncidentsLayerSourceOptions.StyleEnum.S3
    }
    
    // Register the TomTom layer-source
    Mapzania.Services.RegisterTomTomTrafficIncidentsLayerSource("TOMTOM_TRAFFIC", options);
    
    // Start Mapzania
    Mapzania.Services.Start(this);
    
    AreaRegistration.RegisterAllAreas();
    GlobalConfiguration.Configure(WebApiConfig.Register);
    RouteConfig.RegisterRoutes(RouteTable.Routes);
    BundleConfig.RegisterBundles(BundleTable.Bundles);
    ...
}

Start

Starts Mapzania services such as layer-source detection, logging, license-validation and endpoint-activation.

Parameters

Name	Required	Type	Description
app	Yes	System.Web.Http.HttpConfiguration	The configuration object of the web server instance.
options	No	Mapzania.Options	Options for start-up.

Options

Name	Default	Type	Description
LicenseKey	String.Empty	String	The license key of your installation of Mapzania. You can obtain licenses here.
MapStylerAccess	AllowLocal	Mapzania.Access	An enum that sets the web visibility of the MapStyler. Valid values are: - AllowNone (MapStyler is disabled) -AllowLocal (MapStyler can be run on local machine) -AllowAll (MapStyler can be run from any machine)
ServicesAccess	AllowLocal	Mapzania.Access	An enum that sets the web visibility of the ROOT/services endpoints in the REST API. Valid values are: - AllowNone (endpoints are disabled) -AllowLocal (endpoints can be accessed on local machine) -AllowAll (endpoints can be accessed from any machine)

Example

void Application_Start(object sender, EventArgs e)
{
	...
    // Start Mapzania 
    Mapzania.Services.Start(this, new Options {
        MapStylerAccess = Access.AllowLocal,
        ServicesAccess = Access.AllowNone,
        LicenseKey = "<add licence key here>"        
    });

    AreaRegistration.RegisterAllAreas();
    GlobalConfiguration.Configure(WebApiConfig.Register);
    RouteConfig.RegisterRoutes(RouteTable.Routes);
    BundleConfig.RegisterBundles(BundleTable.Bundles);
    ...
}