web.config is used by IIS to start the PowerServer Web APIs (an ASP.NET Core application). It configures which ASP.NET Core application should be invoked and what is the hosting model for the application in the IIS server. It will be ignored when deployed to non-IIS servers.
The web.config file is allowed to be at any level of the IIS folders, but for web.config to take effect, the residing directory must be the web root (such as C:\inetpub\wwwroot) or the app base path. If you place the web.config file in a directory which is not a web root or has not been converted to an IIS sub-app (to become an app base path), the web.config file will not take effect.
-
In IIS, the web root is the main directory where the web site's files and folders are stored. It is the base location from which the server serves the web site's content (such as web.config, ServerAPIs.exe etc.). The web.config file in the web root contains configurations used by the web site, such as the file to launch when the web site URL is run.
-
The app base path is the root directory of an application hosted within IIS. It is the location from which the application's files (such as web.config, ServerAPIs.exe etc.) and resources are served. The web.config file in the app base path contains configurations used by the specific app only, such as the file to launch when the sub app URL is run. Multiple sub apps can be hosted under the same web root, and each sub app can have its own app base path and web.config file.
Note
Multiple web.config files can exist in different folders of the same web site. The setting inheritInChildApplications="false" in the web.config file indicates that the settings will not be inherited by sub-apps.
When deploying the PowerServer Web APIs to IIS or creating a package in the PowerBuilder IDE, the following web.config files are automatically generated:
-
The site web.config file -- Generated in the top-level directory of the package and it is configured to start the ServerAPIs.exe file in the API sub-folder by default.
You can directly copy the site web.config and the API sub-folder to the IIS web root. When the site URL (for example, http://172.16.100.2:82) is run, the site web.config will automatically launch the ServerAPIs.exe file in the API sub-folder.
-
The sub web.config file -- Generated inside the API sub-folder of the package and it is configured to start the ServerAPIs.exe file in the same folder by default.
The sub web.config file is mainly used in two scenarios:
#1: When you copy the entire API sub-folder to the IIS web site and then convert the folder to an IIS sub-app (the API folder becomes an app base path), and then when the sub app URL (the site URL + sub-folder, for example, http://172.16.100.2:82/salesdemo_cloud_API/) is run, the sub web.config file in the API folder will launch the ServerAPIs.exe file in the same folder.
#2: When you copy all files (including sub web.config) from the API sub-folder and place them directly under the IIS web root, and then when the site URL (for example, http://172.16.100.2:82) is run, the sub web.config file (now becomes the site web.config file) will launch the ServerAPIs.exe file in the same folder.
If you compare the contents of these two web.config files, you will find that they have different <add> elements under the <handlers> element. The <handlers> element contains a collection of <add> elements, each of which defines a handler mapping for the application.
-
The site web.config file contains three <add> elements which define three different handlers, each with a specific path and verb.
-
The first handler is configured to handle requests with a path of "/api" and any HTTP verb (verb="*"), such as /api/ServerApi/CreateSession etc.
-
The second handler is configured to handle requests with a path that starts with "/health-" and any HTTP verb, such as /health-ui.
-
The third handler is configured to handle requests with a path of "/connect/token" and any HTTP verb.
The leading forward slash (/) indicates the root of the website.
All three handlers use ASP.NET Core Module (AspNetCoreModuleV2) to process the request.
Note
If you have added new modules or added new interfaces to existing modules, you must configure the module and the handler here, otherwise the request cannot be routed and processed correctly.
By using different handlers with specific paths, you can have more control over how different types of requests are processed and routed within your application.
<handlers> <add name="aspNetCore" path="/api" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" /> <add name="aspNetCore2" path="/health-*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" /> <add name="aspNetCore3" path="/connect/token" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" /> </handlers>Note
If you create and map a new site (or sub-app) to the site where web.config and Web APIs are deployed, and specify the URL of the new site (or sub-app) as the Web API URL, then you must also make sure the handler path includes the new site (or sub-app), for example, you may have to change the path from "/api", "/health-*", "/connect/token" etc. to "new_site_url/api", "new_site_url/health-*", "new_site_url/connect/token", etc.
For example,
path="/powerserver/ReportApiExample/api"
path="/powerserver/ReportApiExample/health-*"
path="/powerserver/ReportApiExample/connect/token"
The leading forward slash (/) indicates the root of the website, and the directory or virtual directory name is specified thereafter.
-
-
The sub web.config file contains only one <add> element and it defines a generic handler for ASP.NET Core applications, using the ASP.NET Core Module (AspNetCoreModuleV2), that will be applied to all requests, regardless of the path or verb.
Note
To use a generic handler for all requests to the ASP.NET Core app, make sure no other static Web apps will be deployed to the same site as the ASP.NET Core app, otherwise the static Web app may not be downloaded successfully.
<handlers> <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" /> </handlers>
