FAQ and Troubleshooting¶
Deploying a Web API with the MIKECore provider.¶
1. Disable shadow copying¶
By default, ASP.NET uses shadow copying, which enables assemblies that are used in an application domain to be updated without unloading the application domain. Basically, it copies your assemblies to a temporary folder and runs your web app from there to avoid locking the assemblies, which would prevent you from updating those assemblies. However, the MIKECore provider is depending on native (C++) DLLs, and as ASP.NET doesn’t copy the native DLLs, you have to turn off shadow copying.
To do this, add the following
<hostingEnvironment> element to your web.config:
<configuration> ... <system.web> ... <hostingEnvironment shadowCopyBinAssemblies="false" />
Using this configuration option will result in the DLLs being locked when the app is running. So if you need to update a DLL, you will need to take the application offline or stop the process before you can do so.
2. Host in a 64-bit environment.¶
Furthermore, The MIKECore provider is depending on assemblies running in a 64-bit environment only, so to configure a Web API with the MIKECore provider hosted in IIS, you must run IIS in 64-bit mode.
How to allow special characters (for example ":") in a URL?¶
By default, there are a number of special characters that ASP.NET does not allow before the "?" in a URL - for example colons (":").
To allow for special characters like ":" in the URL, override the defaults by adding a
requestPathInvalidCharacters attribute to the
<httpRuntime> element in your web.config without the special character that you want to allow.
<configuration> ... <system.web> ... <httpRuntime targetFramework="4.7.1" requestPathInvalidCharacters="<,>,*,%,&,\,?" />
How to allow for a dot (".") in a URL?¶
In some situations, you need to specify a dot (".") in the URL. For example, when using the OpenXML provider, the spreadsheet ID is the filename - including the extension (.xlsx). By default, ASP.NET does not like this.
This can be handled two different ways:
A. Set RAMMFAR to true¶
<modules> element to your web.config and set the
runAllManagedModulesForAllRequests attribute to true.
<configuration> ... <system.webserver> ... <modules runAllManagedModulesForAllRequests="true">
However, setting RAMMFAR to true has some implications. Instead, consider adding an alternative HTTP handler as described below.
B. Add an alternative HTTP handler¶
Add an alternative HTTP handler to your web.config file.
<configuration> ... <system.webserver> ... <handlers> ... <add name="MySpreadsheetHandler" path="api/spreadsheet/*" verb="*" type="System.Web.Handlers.TransferRequestHandler" preCondition="integratedMode,runtimeVersionv4.0" />
If you have a combination of multiple web APIs within one project, for example spreadsheets and GIS, it is probably not a good idea simply to set the
path attribute to "*". Instead, set the
path attribute to "api/*" or add multiple explicit handlers.
Which type of connection shall I choose?¶
The Domain Services Web APIs are configured using so-called Connections. There are different types of connections for accessing time series, feature collections, spreadsheets etc. But even within the individual domains - for example time series - there are multiple connections to choose from. If you have installed the Time Series Web API nuget package (
DHI.Services.TimeSeries.Web) in your project, then you will have the following options, when selecting a time series connection type.
Which one to actually choose depends on the circumstances - for example which repository type you intend to use, because all repository types does not necessarily support all connection types. For example the
Dfs0TimeSeriesRepository does not support adding a new time series or organizing the time series in a hierarchy of groups, so it only works with the
TimeSeriesServiceConnection and the
DiscreteTimeSeriesServiceConnection, but is not compatible with any of the other connection types.
When using the API Administrator, it will automatically detect the available (installed) repository types that are compatible with the selected connection type.
The characteristics of the different time series connection types are the following:
TimeSeriesServiceConnection. This is the simplest form of a time series service connection. It has a quite comprehensive API, but it is all read-only functionality. All time series repositories supports this connection type.
DiscreteTimeSeriesServiceConnection. This connection type assumes that the underlying time series repository comprise a finite (discrete) number of time series. This is not always the case. For example in the
dfs2TimeSeriesRepository, a time series can be extracted using the geographic coordinates. So a dfs2-file comprises an in-finite number of time series. Assuming that the repository comprises a finite number of time series, the API can be extended with methods like
GroupedDiscreteTimeSeriesServiceConnection. This connection types assumes that the underlying time series repository supports organizing time series in a hierarchy of groups. Under this assumption, methods such as
GetFullNamescan be introduced in the API. This is the case for example in the MIKE OPERATIONS time series repository and certain file-based repositories.
UpdatableTimeSeriesServiceConnection. The updatable (and disctrete) time series connection adds methods like
Updateto the API. Grouping is not supported. An example of a repository supporting this connection type is the WaterForecast
GroupedUpdatableTimeSeriesServiceConnection. This connection type comprise everything from the
UpdatableTimeSeriesServiceConnectionand adds grouping (
GetFullNamesetc.) to the API. An example of a time series repository that supports this connection type is the
Within other domains such as GIS, Rasters, Spreadsheets etc. a similar approach is used.
How do I configure Swagger to incorporate the XML-annotations for a Web API?¶
When using the Visual Studio project templates, by default, most of the Web API project templates come with swagger support and are configured to use the XML-annotations of the Web APIs that are included in the template.
However, if you use one of the generic templates, where you add additional Web APIs to the project, you have to manually configure Swagger to use the XML-annotations of these added Web APIs. This is done in the
SwaggerConfig.cs file found in the
App_Start folder. In the below example, the XML-annotations of the Time Series Web API are incorporated in the Swagger documentation.