TOPICA has one Web.config file in the framework folder (= the folder the web home points to) like most other ASP.NET applications.

• Web.config:

  • This file is part of the framework, i.e. it will exist in the framework folder after setting up a web home for the TOPICA framework.

  • Only framework developers should edit this file. All other roles (configurators, application developer) are not allowed to edit this file - - but they WILL need to read this file, as this is the file that defines all the "appSettings", that the TOPICA framework understands!

  • The framework understands more than 1000 "appSettings". The default value for each setting is defined by Web.config.

The TOPICA framework supports several configurations(=applications) in one instance (web home). It is necessary to configure each individual configuration separately.

A given application will typically run in several different environments (development, test, production, ...). Most settings should be the same for each environment, but some key settings (like database connection strings, URL's used for interfaces, etc.) must be configurable per environment.

Therefore, TOPICA read additional .config files from the configuration folder:

• Application.config

  • Application.config holds settings (key/value pairs) for the actual application (= configuration) - regardless of the current environment (the SAME Application.config file should be used in all environments).

  • Typically, you would keep the Application.config file under source control together with all other configuration items (forms, reports, ...). This makes it easier to remember to deploy the Application.config each time you update a configuration.

  • Application.config MUST exist in each configuration folder.

  • Application.config, may override any key set in framework's Web.config.

  • Application.config may define new, configuration specific keys. Remember to describe the function of the new keys in XML comments!

    The purpose of defining new, configuration specific keys, is to make configuration specific features configurable. This is done by TOPICA Basic expressions, for example in the following places:

    • Show/hide fields in forms.

    • Defining computations in the structure file to control security and/or workflow.

    Refer to .config-file reference for examples.

• Optional activated "library" .config-files

  • Note
    Versions 4.27 and newer only. Refer to ConfigLibrary.

• Server.config

  • Server.config holds settings (key/value pairs) for the actual environment / server. For example, the connection string for the database - this is typically not the same in development and production environments.

  • The Server.config file should NOT be kept under source control. This makes it easier to remember NOT to overwrite Server.config on deployment - e.g. when copying configuration items from development to production.

  • Server.config MUST exist in each configuration folder.

  • Server.config, may override any key set in the framework's Web.config, the configuration's Application.config, (AND (in versions 4.27 and newer) any "activated" files in the ConfigLibrary).

  • Server.config should NOT define new, configuration-specific keys.

• Optional Web.config:

  • An optional configuration/application specificWeb.config file holds "structured" information, that cannot be stored in Application.config.

  • This file is only used in a few special cases ("custom " .NET code - e.g. custom webforms and custom webservices). Most applications do not need one.

  • Caution
    Do NOT confuse this configuration specific Web.config file with the framework's Web.config in the website folder!

Application.config and Server.config must adhere to the same syntax as the central Web.config, except that the only supported section is the appSettings section.

The framework's Web.config file contains all the settings (key/value pairs) the framework knows about. Each setting is documented by comments in the file (ideally!). Both Application.config and Server.config are used to "override" settings defined in Web.config in the website (the framework's .config file) - thus changing the framework's behavior in the current configuration/application.

It is possible to add settings to Application.config and Server.config that do not exist in the framework's Web.config. These setting will of course not influence on the behavior of the framework. Such settings are used by the configuration items. For example, rules/computations in configured forms may check such settings to display the forms differently depending on environment.

Note that this system dictates, that the framework's Web.config (the one in the website) must NOT be edited per application / environment. Only Role Framework Developer may edit the framework's Web.config file. Role Configurator may edit Application.config, Server.config and Web.config - all of them placed in the configuration folder. Role Configurator may NOT edit the framework's Web.config file!

<framework folder>
    Configuration
        MyConfig1
            Application.config
            Server.config
            Web.config
        MyConfig2
            Application.config
            Server.config
    Web.config

In this example the framework instance contains 2 configurations. The configuration MyConfig1 contains a configuration specific Web.config file - the configuration MyConfig2 does not. Both configuration contain the required Application.config and Server.config files.

The framework does not contain any tools to edit .config files. I.e. you need access to the web server's file system to edit the contents of the .config files.

You may use any tool capable of editing XML-files to edit .config files. This includes "plain text editors" like Notepad, and XML-aware editors like Visual Studio.

Tip
It is recommended to use Visual Studio for editing .config-files. Not only does it "understand" XML, but it also has a built-in schema (XSD) for .config files, so that it "knows" what elements and attributes are allowed (this is how "intellisense" works).

Consult .config File Reference for more detailed reference.

Because all parameters may be overwritten, it may be hard to get an overview of the effective value of each key. A typical example is, that a configurator has defined a key to having some value in Application.config - but it does not have the desired effect. This might be because the key is also defined in Server.config, thereby overriding the value set in Application.config.

To help with this, the framework contains a page, that lists the effective value of each configured key. This Webform may be found here: Main menu: Tools / Framework Tools - select Information / ConfigAppSettings.aspx.

In TOPICA versions 4.27 and newer, an additional mechanism ConfigLibrary exists.

The purpose of this is to make it possible for configurator / deployers to create a "library" of .config-files, that may be turned on/off (activated / deactivated) using the web interface.