How to Leverage the Domain Services¶
There a 3 different ways to use the Domain Services:
At the lowest level, you can use the Domain Services as a framework for developing domain-driven and service-oriented architectures (SOA).
At a higher level, the Domain Services provide a number of data-agnostic stateless service components within various common domains such as time series data and -analysis, geospatial data and -analysis, job execution etc.
At the highest level you can use the Web API components which expose the functionality through REST/HTTP APIs.
All Domain Services components are .NET assemblies (dlls) published as NuGet packages.
In the following, each of the 3 different use cases are described in more details.
Using the Domain Services as a framework¶
The Domain Services Core (
DHI.Services) provides a collection of generic interfaces and abstract base classes for domain driven design types such as entities, services and repositories. It also provides higher-level functionality such as:
- A framework for configuring, initializing and accessing service instances
- A generic fake (in-memory) repository for unit testing
- Services for logging, user account management and sending e-mail
Thus, the Domain Services Core can be used as a generic framework for establishing a service-oriented architecture, if none of the higher-level "pre-baked" services fit your needs. This is exactly how it is used in for example the Data Broker API of the Water Data Platform.
To use the Domain Services as a SOA-framework, simply install the
DHI.Services NuGet package from one of the internal NuGet feeds.
Using the Service Components¶
On top of the core types, the Domain Services provide a layer of stateless service components within various functionality- and data domains such as time series data and -analysis, geospatial data and -analysis and job execution.
Typical use cases for leveraging these service components could be if you are building a classical Windows .NET application, in scripting scenarios, or if you are building a Web API, but want to use a different approach than offered by the prebaked Web API components - for example another security model or even a different Web API development framework.
So far, the service components have been used in for example the Windows .NET applications Amelia (next generation MIKE Urban) and the Model Predictive Control (MPC) engine. They also form the basis for some of the Web APIs of the Water Data Platform - for example the Time Series API, the GIS API and the Mesh Data API.
The service components are all data agnostic - meaning that data storage is abstracted away using repository interfaces, so that the service layer components can work with data from heterogeneous data sources - as long as a data provider for the data source is implemented. Out of the box, Domain Services provide a number of providers for common storage formats such as dfs-files, shape-files, the DIMS.CORE database, the MIKE Operations database and many more. All of these providers are available as NuGet packages.
For example, to use the Domain Services to retrieve and analyze time series data from a MIKE Operations database, simply install the
DHI.Services.MCLite NuGet package from one of the internal NuGet feeds.
Using the Web API Components¶
Finally, you can go all the way and use the Web API components as provided out of the box by the Domain Services. Each of the individual service components comes with a corresponding HTTP-based Web API component. This means that they can be deployed as individual microservices in compliance with the Architecture Blueprint.
The higher you go in the Domain Services stack, the more decisions have been made, and the more dependencies are introduced. The Domain Services Web APIs are made using the ASP.NET Web API framework and the security model is Basic Authentication.
All of the Web API components support versioning according to the general API versioning guidelines of DHI.
One of the biggest advantages of the Web API components are that many of them come with a UI in the form of Polymer web components - or even web sites. For example, we have a Polymer element that integrates with the GIS API for rendering vector graphics on a map, and the Core Web API Component
DHI.Services.Web is bundled with an API Administrator web site for administration of user accounts and service connections.
The Web API components, in combination with the Polymer web components, have been used in numerous web applications - for example the prize-winning NCOS Online solution for Port of Brisbane in Australia.
The easiest and best way to leverage the Web API components is by using the Domain Services Visual Studio project templates. These project templates can be installed as a Visual Studio 2017 extension using the Software Center (preferably Internet Explorer).
Once installed, you can see (and disable and uninstall) this extension from the Tools -> Extensions and Updates... menu in Visual Studio.
Now, you have the Domain Services Web API project templates available side-by-side the Visual Studio default project templates.
The "DHI Domain Services Web API" project template is used to set up one single project with multiple service-specific APIs (for example a combination of Time Series, GIS and Jobs).
The other templates are targeted microservice-deployment, where for example Time Series, GIS and Jobs are deployed as individual services.
By default, the project templates are set up to use the Azure DocumentDB (CosmosDB) provider for user account storage, but this is configurable. User account management is done using the Core Web API component.
The project templates all come with a number of pre-defined sample connections (in the
connections.json file), and some of them even have some sample data in the
App_Data folder corresponding to the sample connections, but no service-specific providers are pre-installed. Furthermore, all templates provide a Swagger endpoint for documentation and test.
Thus, setting up for example a Time Series Web API for a MIKE Operations database, deployed as a microservice, can be done using the following steps:
- Create a new project using the "DHI Domain Services Time Series Web API" template
- Install the NuGet package
- Build and debug the project
- Use the API Administrator web site to configure your connections
- Using the Visual Studio Publish tool, deploy your API to for example an Azure App Service, to IIS or simply to a folder.