Remote Agent Web API Service Implementation

Remote Agent Web API is an API designed to securely allow connections into a client’s environment to grant access to information/data based on providers (such as databases, file share, etc.). Remote Agent Web API initially supports access to Microsoft SQL Server and Polar DB databases which are accessible to the host system - access is granted to the SQL Utility Connector using the configured Remote Agent credentials. Future versions will support additional features such as other databases (MySQL, Oracle, etc.), file share, or external sources. Version 1.0 uses Basic Authentication.

For details about the latest updates including support for additional technology, bug fixes and more, see Remote Agent Web API Service Reference.

Pre-requisites

Operating System Requirements

  • Windows 7 or higher
  • Windows Server 2012 R2 or higher

Supported Platforms

Apps published for 32-bit (x86) or 64-bit (x64) deployment are supported.

32-bit apps

Deploy a 32-bit app with a 32-bit (x86) .NET Core SDK unless the app:

  • requires the larger virtual memory address space available to a 64-bit app.

  • requires the larger IIS stack size.

  • has 64-bit native dependencies.

Apps published for 32-bit (x86) must have 32-bit enabled for their IIS Application Pools. For more information, see the Create the IIS site section below.

64-bit apps

Use a 64-bit (x64) .NET Core SDK to publish a 64-bit app.

A 64-bit runtime must be present on the host system.

Process Manager

An ASP.NET Core app is a console app that must be started when a server boots up and must be restarted if the service crashes.

To automate starts and restarts, a process manager is required. The most common process managers for ASP.NET Core are:

.NET Core Hosting Bundle

The .NET Core Hosting Bundle installs the .NET Core Runtime, .NET Core Library, and the ASP.NET Core Module. This module allows ASP.NET Core apps to run behind IIS.

Setup

These setup instructions demonstrate

IIS Configuration

Windows Server operating systems

This section outlines how to set up IIS if it is not already configured. If IIS is already installed, review “Role Services” to ensure all requirements are met.

Enable the Web Server (IIS) server role and establish role services.

To do this:

  1. Use the Add Roles and Features wizard from the Manage menu or the link in Server Manager.

    On the Server Roles step, check the box for Web Server (IIS).

  2. After the Features step, the Role Services step loads for Web Server (IIS). Select the IIS role services desired or accept the default role services provided.

    • Windows Authentication (Optional)

      To enable Windows Authentication, expand the following nodes: Web Server > Security. Select the Windows Authentication feature. For more information, see Windows Authentication <windowsAuthentication> and Configure Windows authentication.

    • WebSockets (Optional)

      WebSockets is supported with ASP.NET Core 1.1 or later. To enable WebSockets, expand the following nodes: Web Server > Application Development. Select the WebSocket Protocol feature. For more information, see WebSockets.

  3. Proceed through the Confirmation step to install the web server role and services. A server/IIS restart isn’t required after installing the Web Server (IIS) role.

Windows Server operating systems

Enable the IIS Management Console and World Wide Web Services.

  1. Navigate to Control Panel > Programs > Programs and Features > Turn Windows features on or off (left side of the screen).

  2. Open the Internet Information Services node. Open the Web Management Tools node.

  3. Check the box for IIS Management Console.

  4. Check the box for World Wide Web Services.

  5. Accept the default features for World Wide Web Services or customize the IIS features.

    • Windows Authentication (Optional)

      To enable Windows Authentication, expand the following nodes: World Wide Web Services > Security. Select the Windows Authentication feature. For more information, see Windows Authentication <windowsAuthentication> and Configure Windows authentication.

    • WebSockets (Optional)

      WebSockets is supported with ASP.NET Core 1.1 or later. To enable WebSockets, expand the following nodes: World Wide Web Services > Application Development Features. Select the WebSocket Protocol feature. For more information, see WebSockets.

  6. If the IIS installation requires a restart, restart the system.

Install the .NET Core Hosting Bundle

Install the .NET Core Hosting Bundle on the hosting system. The bundle installs the .NET Core Runtime, .NET Core Library, and the ASP.NET Core Module. The module allows ASP.NET Core apps to run behind IIS.

Important Installation Note

  • If the Hosting Bundle is installed before IIS, the bundle installation must be repaired. Run the Hosting Bundle installer again after installing IIS.

  • If the Hosting Bundle is installed after installing the 64-bit (x64) version of .NET Core, SDKs might appear to be missing (No .NET Core SDKs were detected). To resolve the problem, see Troubleshoot and debug ASP.NET Core projects.

Direct download (current version)

Download the installer using the following link: Current .NET Core Hosting Bundle installer (direct download).

Earlier versions of the installer

To obtain an earlier version of the installer:

  1. Navigate to the Download .NET Core page.

  2. Select the desired .NET Core version.

  3. In the Run apps - Runtime column, find the row of the .NET Core runtime version desired.

  4. Download the installer using the Hosting Bundle link.

Warning

Some installers contain release versions that have reached their end of life (EOL) and are no longer supported by Microsoft. For more information, see the support policy.

Hosting Bundle installation instructions

  1. Run the installer on the server. The following parameters are available when running the installer from an administrator command shell:

    • OPT_NO_ANCM=1: Skip installing the ASP.NET Core Module.

    • OPT_NO_RUNTIME=1: Skip installing the .NET Core runtime. Used when the server only hosts self-contained deployments (SCD).

    • OPT_NO_SHAREDFX=1: Skip installing the ASP.NET Shared Framework (ASP.NET runtime). Used when the server only hosts self-contained deployments (SCD).

    • OPT_NO_X86=1: Skip installing x86 runtimes. Use this parameter when you know that you won’t be hosting 32-bit apps. If there’s any chance that you will host both 32-bit and 64-bit apps in the future, don’t use this parameter and install both runtimes.

    • OPT_NO_SHARED_CONFIG_CHECK=1: Disable the check for using an IIS Shared Configuration when the shared configuration (applicationHost.config) is on the same machine as the IIS installation. Only available for ASP.NET Core 2.2 or later Hosting Bundler installers. For more information, see ASP.NET Core Module.

  2. Restart the system or execute the following commands in a command shell:

    net stop was /y
net start w3svc

    Restarting IIS picks up a change to the system PATH, which is an environment variable, made by the installer.

    ASP.NET Core doesn’t adopt roll-forward behavior for patch releases of shared framework packages. After upgrading the shared framework by installing a new hosting bundle, restart the system or execute the command above.

Create the IIS site

  1. On the hosting system, create a folder to contain the app’s published folders and files. In a following step, the folder’s path is provided to IIS as the physical path to the app. For more information on an app’s deployment folder and file layout, see ASP.NET Core directory structure.

  2. In IIS Manager, open the server’s node in the Connections panel.

    Right-click the Sites folder.

    Select Add Website from the contextual menu.

  3. Provide a Site name and set the Physical path to the app’s deployment folder.

    Provide the Binding configuration and create the website by selecting OK.

    Warning

    Top-level wildcard bindings (http://*:80/ and http://+:80) should not be used. Top-level wildcard bindings can open up your app to security vulnerabilities. This applies to both strong and weak wildcards.

    To minimize risk, use explicit host names rather than wildcards. Subdomain wildcard binding (for example, *.mysub.com) doesn’t have this security risk if you control the entire parent domain (as opposed to *.com, which is vulnerable). See rfc7230 section-5.4 for more information.

  4. Under the server’s node, select Application Pools.

  5. Right-click the site’s app pool and select Basic Settings from the contextual menu.

  6. In the Edit Application Pool window, set the .NET CLR version to No Managed Code.

    ASP.NET Core runs in a separate process and manages the runtime. ASP.NET Core doesn’t rely on loading the desktop CLR (.NET CLR). The Core Common Language Runtime (CoreCLR) for .NET Core is booted to host the app in the worker process. Setting the .NET CLR version to No Managed Code is optional but recommended.

  7. ASP.NET Core 2.2 or later:

    1. For a 32-bit (x86) self-contained deployment published with a 32-bit SDK that uses the in-process hosting model, enable the Application Pool for 32-bit.

      In IIS Manager, navigate to Application Pools in the Connections sidebar.

      Select the app’s Application Pool.

      In the Actions sidebar, select Advanced Settings.

      Set Enable 32-Bit Applications to True.

    2. For a 64-bit (x64) self-contained deployment that uses the in-process hosting model, disable the app pool for 32-bit (x86) processes.

      In IIS Manager, navigate to Application Pools in the Connections sidebar.

      Select the app’s Application Pool.

      In the Actions sidebar, select Advanced Settings.

      Set Enable 32-Bit Applications to False.

  8. Confirm the process model identity has the proper permissions.

    If the default identity of the app pool (Process Model > Identity) is changed from ApplicationPoolIdentity to another identity, verify that the new identity has the required permissions to access the app’s folder, database, and other required resources.

    For example, the app pool requires read and write access to folders where the app reads and writes files, including application logs.

Publish & deploy the Remote Agent Web API

Contact your Implementation Consultant for the latest version of the Remote Agent Web API application. Provided application contents are moved to the IIS site’s folder (the Physical Path assigned in IIS Manager). After the app is deployed to the hosting system, make a request to one of the app’s public endpoints.

In the following example, a request is made to http://59.94.176.2:6050/swagger/index.html

Configuration

appsetting.json

appsetting.json file is used to define Basic Authentication details used to connect to the Remote Agent Web API, and well as the credentials used to by the Remote Agent Web API to connect to system applications (such as Microsoft SQL Server). Complete the ConnectionDetails section to configure the require credentials.

UserName / Password define the Remote Agent Web API username and password that grant access to use a configured connection string. This is something you create as part of the Remote Agent Web API and should not match application credentials used to authenticate with a system such as Microsoft SQL Server.

ConnectionString defines the application’s connection string.