Hide

YetaWF Documentation

Display
Print

AppSettings.json

Many portions of the AppSettings.json file are predefined by YetaWF. Most packages allow configuration settings to be managed using pages on your web site, typically part of Admin > Settings (standard YetaWF site).

There are instances where information has to be provided using the website's AppSettings.json file, typically when the information is required to start the site.

The AppSettings.json file used for development is located in folder ./Website/Data. The file ./Website/Data/AppSettings.Prod.json is the equivalent file for production which is deployed as AppSettings.json.

AppSettings.json Syntax

{
  "Variables": {            // Variables
    "SQLLegacyFax": "Data Source=....;Initial Catalog=PROD....;User ID=username;Password=password",
    "SQLLegacyFaxDATA": "Data Source=....;Initial Catalog=PROD....;User ID=username;Password=password",
    "SQLLegacyFaxSTORE": "Data Source=....;Initial Catalog=PROD....;User ID=username;Password=password"
  },
  "Logging": {              // Logging section
    "IncludeScopes": false,
    "LogLevel": {
      "Default": "Warning",
      "System": "Warning",
      "Microsoft": "Warning"
    }
  },
  "Application": {          // YetaWF section used to configure defaults and packages
    "SessionState: {
      "Timeout": 1440,
      "CookieName": ".YetaWF.Session",
      "Provider": "{SQL|Redis|}",
      "SqlCache-Connection": "Data Source=..datasource..;Initial Catalog=..catalog..;User ID=..userid..;Password=..password..",
      "SqlCache-Schema": "dbo",
      "SqlCache-Table": "..SessionStateCache..",
      "RedisConfig": "..localhost:6379.."
    },

    "P": {                  // Configuration section
      "MvcApplication": {
        "LogoffUrl": "/YetaWF_Identity/LoginDirect/Logoff?NextUrl="
      },
      "StaticFiles": {
        "Duration": 0
      },
      "Default": {
        "LanguageId": "{en-US|..languageid..}",
        "IOMode": "{File|SQL}",
        "SQLDbo": "dbo",
        "SQLConnect": "Data Source=..datasource..;Initial Catalog=..catalog..;User ID=..userid..;Password=..password..",
        "SourceFolder_Templates": "Templates",
        "SourceFolder_Utilities": "Utilities",
        "SourceFolder_Modules": "Modules",
        "SourceFolder_Skins": "Skins",
        "SourceFolder_Core": "CoreComponents",
        "SourceFolder_DataProvider": "DataProvider"
      },
      "Identity": {
        "Assembly": "YetaWF.Identity",
        "Type": "YetaWF.Modules.Identity.Startup"
      },
      "Logging": {
        "Assembly": "YetaWF.Logging",
        "Type": "YetaWF.Modules.Logging.DataProvider.NLogProvider.LogRecordDataProvider",
        "(Sql) Type": "YetaWF.Modules.Logging.DataProvider.SQL.LogRecordDataProvider",
        "(File) Type": "YetaWF.Modules.Logging.DataProvider.File.LogRecordDataProvider",
        "MinLevel": 0
      },

      // Packages

      "YetaWF_Core": {
        "MaxRequestBodySize": { 0 | ..size.. },
        "INITIAL-INSTALL": {true|false},
        "DEFAULTSITE": "...yourdomain.com..",
        "DEBUG-MODE": {true|false},
        "Diagnostics": {true|false},
        "Demo": false,
        "Deployed": {true|false},
        "UseCDN": {true|false},
        "UseCDNComponents": {true|false},
        "UseStaticDomain": {true|false},
        "DisposableTracker": {true|false},
        "LOCKED-FOR-IP": "{..ipaddress..|}",
        "Use-Localization-Resources": {true|false},
        "Fail-On-Missing-Localization-Resource": {true|false}
      },

      // Other packages

      . . .

      // YetaWF.Identity package

      "YetaWF_Identity": {
        "BACKDOOR-IS-WIDE-OPEN": {true|false},
        "SuperUserName": "..superusername..",
        "BatchKey": "..guid.."
        . . .
      },

      . . .

    }
  }
}

Environment Variables

Environment variables can override individual settings. All environment variable overrides start with the prefix "YETAWF_" and are all caps. This is typically used with Docker and docker compose files.

Only entries in the "Application" section can be overridden using environment variables, by using the complete path to the variable.

For example, the "Duration" setting in AppSettings would use the following environment variable:

YETAWF_P_STATICFILES_DURATION=500

UseCDN in the YetaWF_Core section can be overridden use the following environment variable:

YETAWF_P_YETAWF_CORE_USECDN=true

[Debug] Prefix

Any setting name can be prefixed with [Debug] in which case it only applies in a DEBUG BUILD:

{
  . . .
  "Application": {          // YetaWF section used to configure defaults and packages
    . . .
    "P": {                  // Configuration section
      . . .
      "StaticFiles": {
        "Duration": 500
        "[Debug]Duration": 0
      },
      . . .
      "YetaWF_Core": {
        . . .
        "DEBUG-MODE": false,
        "[Debug]DEBUG-MODE": true,
      },
      . . .
    }
  }
}

Data Provider Source

Currently data providers included with YetaWF can use SQL DBs or simple file I/O to store site data (some packages are SQL only). The overall defaults for all data providers are defined using Application.P.Default.IOMode.

For individual data providers, even within the same package, you can override this default. This means you can mix and match so some data providers can use file I/O, while others use SQL DBs. Or data providers can be directed to different SQL DBs.

Variable Substitution

Using Defined Variables

To avoid repeating the same information, variable substitution can be used. A special "Variables" section can be used which makes all listed string variables available for string values used in AppSettings.json. Only string variables and string values are supported.

This example uses 3 different SQL connection strings as variables. These can be referenced in string values by using [Var,variablename] which is replaced with the variable's value.

{
  "Variables": {
    "SQLLegacyFax": "Data Source=....;Initial Catalog=PROD....;User ID=username;Password=password",
    "SQLLegacyFaxDATA": "Data Source=....;Initial Catalog=PROD....;User ID=username;Password=password",
    "SQLLegacyFaxSTORE": "Data Source=....;Initial Catalog=PROD....;User ID=username;Password=password"
  },
  ...
  "Default": {
    "LanguageId": "en-US",
    "IOMode": "SQL",
    "SQLDbo": "dbo",
    "SQLConnect": "[Var,SQLLegacyFax]",
    ...
  },
  ...

Using Environment Variables

Environment variables can be used with variable substitution throughout AppSettings.json by using which is replaced with the environment variable's value. This is typically used with Docker and docker compose files.

{
  "Variables": {
    "SQLLegacyFax": "[Env,SQLCONNECTIONSTRING]",
    "SQLDbo":
  },
  ...
  "Default": {
    "LanguageId": "en-US",
    "IOMode": "SQL",
    "SQLDbo": "[Env, SQLDBO]",
    "SQLConnect": "[Var,SQLLegacyFax]",
    ...
  },
  ...

AppSettings Entries

Application.P.Default.IOMode

The default I/O Mode for all data providers is defined using the Application.P.Default.IOMode setting. Currently File and SQL values are possible.

Application.P.Default.IOMode - File

Defines the default I/O mode for all data providers using file I/O.

{
  "Application": {
    . . .
    "P": {
      . . .
      "Default": {
        . . .
        "IOMode": "File",
        . . .
Application.P.Default.IOMode - SQL

Defines the default I/O mode for all data providers using SQL DBs with the specified dbowner dbo and the connection string specified using Application.P.Default:SQLConnect.

{
  "Application": {
    . . .
    "P": {
      . . .
      "Default": {
        . . .
        "IOMode": "SQL",
        "SQLDbo": "dbo",
        "SQLConnect": "Data Source=....;Initial Catalog=....;User ID=username;Password=password",
Override

For each individual DataProvider implemented in YetaWF packages, you can override the default IOMode settings, where area is the Package Area Name, optionally followed by name. The optional name is specific and can be found in the DataProvider documentation for the package in question.

    "P": {
      . . .
      "area_name": {
        . . .
        "IOMode": "SQL",
        . . .
        "IOMode": "SQL",
        "SQLDbo": "dbo",
        "SQLConnect": "Data Source=....;Initial Catalog=....;User ID=username;Password=password",

Logging

Defines the .NET logging options. Not otherwise used by YetaWF.

  "Logging": {              // .NET  Logging
    "IncludeScopes": false,
    "LogLevel": {
      "Default": "Warning",
      "System": "Warning",
      "Microsoft": "Warning"
    }
  },

Application.SessionState

Defines the SessionState repository on .NET.

SessionState can be use either a SQL database table, a Redis server or in-memory caching.

{
  "Application": {          // YetaWF section used to configure defaults and packages
    "SessionState: {
      "Timeout": 1440,
      "CookieName": ".YetaWF.Session",
      "Provider": "{SQL|Redis|}",
      "SqlCache-Connection": "Data Source=..datasource..;Initial Catalog=..catalog..;User ID=..userid..;Password=..password..",
      "SqlCache-Schema": "dbo",
      "SqlCache-Table": "..SessionStateCache..",
      "RedisConfig": "..localhost:6379.."
    }
  }
}
ArgumentDescription
TimeoutDefines the number of minutes after which a session times out and becomes invalid.
CookieNameDefines the name of the cookie used.
ProviderDefines whether SQL, Redis or in-memory caching is used for session state services. If SQL is used, SQLDbo and SQLConnect must also be defined. For Redis, RedisConfig must also be defined. If Provider is defined as an empty string, in-memory caching is used.
RedisConfigDefines the Redis server when Provider is set to Redis. The same Redis server can be used for caching and locking services. The default is localhost:6379.
SqlCache-ConnectionDefines the SQL connection string when Provider is set to SQL. This must be specified (no default is used), otherwise in-memory caching is used.
SqlCache-SchemaDefines the database owner when Provider is set to SQL. This must be specified (no default is used), otherwise in-memory caching is used.
SqlCache-TableDefines the database table when Provider is set to SQL. This must be specified (no default is used), otherwise in-memory caching is used.
SQL

When using SQL based session state, the database table must be initialized using the dotnet utility, part of the .NET SDK.

dotnet sql-cache create "Data Source=..datasource..;Initial Catalog=..catalog..;User ID=..userid..;Password=..password.." dbo SessionStateCache

Application.P.Default.LanguageId

Defines the default language for all sites within this instance of YetaWF. When YetaWF is installed this is configured automatically.

This is a required entry.

    "P": {
      . . .
      "Default": {
        . . .
        "LanguageId": "en-US",
        . . .

Application.P.Default.SourceFolder(s)

Defines where source files are located relative to the solution folder. These values don't need to be specified and have suitable default values. These values are only changed when testing importing packages.

Application.P.Identity

Defines the assembly (Assembly) that implements authentication services. The specified type (Type) is instantiated during application startup to initialize the assembly and the associated authentication services. The package YetaWF.Identity is provided with YetaWF and implements all services.

Application.P.YetaWF_Core.DEFAULTSITE

Defines the default site hosted by YetaWF. Your YetaWF instance can host multiple sites, but one site has to be defined as the default site. If a request is received by YetaWF for a domain which doesn't match any of the domains defined by your sites, the default site is used.

This entry is required.

    "P": {
      . . .
      "YetaWF_Core": {
        . . .
        "DEFAULTSITE": "..yoursite.com..",
        . . .

Application.P.YetaWF_Core.DEBUG-MODE

Defines whether the site runs in "Debug" mode, which means that most caching and response compression are disabled (see Admin > Settings > Site Settings (standard YetaWF site), Pages tab). This setting is independent of whether you compiled YetaWF in Debug or Release mode. By setting the Application.P.YetaWF_Core.Deployed value to false, yet running a Debug build you can fully debug how the site would run in release mode as far as caching and response compression are concerned.

This setting is ignored in a Release builds and defaults to false.

    "P": {
      . . .
      "YetaWF_Core": {
        . . .
        "DEBUG-MODE": "true",
        . . .

Application.P.YetaWF_Core.Diagnostics

Defines whether the site runs with additional diagnostics enabled. This is typically is while developing a site. It enables additional file presence verifications and suppresses some exception spam.

Application.P.YetaWF_Core.Demo

Defines whether the YetaWF instance runs in Demo Mode. When in Demo Mode, the site can't be modified, but all users, even anonymous users, have access to all pages of the web site.

This setting defaults to false.

    "P": {
      . . .
      "YetaWF_Core": {
        . . .
        "Demo": "true",
        . . .

Application.P.YetaWF_Core.Deployed

Defines whether the site is a deployed site, i.e., running in production mode. This setting is independent of whether you compiled YetaWF in Debug or Release mode. By setting the Application.P.YetaWF_Core.Deployed value to true, yet running a Debug build you can fully debug how the site would run fully deployed.

This setting is ignored in a Release builds and defaults to true.

    "P": {
      . . .
      "YetaWF_Core": {
        . . .
        "Deployed": "true",
        . . .

Application.P.YetaWF_Core.DisposableTracker

Defines whether objects that implement the IDisposable interface are tracked so objects that are not disposed can be located. Admin > Dashboard > Disposable Tracker (standard YetaWF site) can be used to view tracked objects.

This should only be enabled in development mode as there is a performance penalty.

Application.P.YetaWF_Core.Fail-On-Missing-Localization-Resource

Defines whether missing localization resource strings cause a failure exception or are silently ignored. This should only be set to true in development mode or when using automated testing tools to find missing resource strings.

This setting can be modified using Admin > Settings > Localization Settings (standard YetaWF site).

Application.P.YetaWF_Core.INITIAL-INSTALL

Defines whether the current application startup is an initial install. This should be set to false, except when installing YetaWF for the very first time.

Application.P.YetaWF_Core.LOCKED-FOR-IP

Used to lock out access to everyone except the specified IP address.

This setting defaults to an empty string, i.e., no IP address.

This is automatically set/reset when using Admin > Settings > Site Settings, Site tab and selecting the Locked property. This updates AppSettings.json with your IP address and restarts the site.

    "P": {
      . . .
      "YetaWF_Core": {
        . . .
        "LOCKED-FOR-IP": "127.0.0.1",
        . . .

Application.P.YetaWF_Core.MaxRequestBodySize

Defines the maximum allowed size of any request body in bytes. When set to 0, the maximum request body size is unlimited. This limit has no effect on upgraded connections which are always unlimited. Defaults to 30,000,000 bytes.

Application.P.YetaWF_Core.Use-Localization-Resources

Defines whether localization resources are used. Theses are files located in the ./Website/Localization and ./Website/LocalizationCustom folders. They contain strings and data, localized for different languages.

If multi-language support is required, this property must be enabled. This property applies to ALL sites run by this instance of YetaWF.

This setting can be modified using Admin > Settings > Localization Settings (standard YetaWF site).

Application.P.YetaWF_Core.UseCDN

Defines whether a Content Delivery Network (CDN) can be used for YetaWF files if it has been properly set up using Site Settings, CDN tab. This is typically used to turn a CDN off, so site settings don't need to be modified.

This setting defaults to false.

    "P": {
      . . .
      "YetaWF_Core": {
        . . .
        "UseCDN": "true",
        . . .

Application.P.YetaWF_Core.UseCDNComponents

Defines whether a Content Delivery Network (CDN) can be used for external files, if it has been properly set up using Site Settings, CDN tab. This is typically used to turn a CDN off, so site settings don't need to be modified.

This setting defaults to false.

    "P": {
      . . .
      "YetaWF_Core": {
        . . .
        "UseCDNComponents": "true",
        . . .

Application.P.YetaWF_Core.UseStaticDomain

Defines whether the static domain defined in Site Settings is used. This is typically used to turn a static domain off (in development), so site settings don't need to be modified.

Application.P.MvcApplication.LogoffUrl

Defines the URL to log the current user off. When YetaWF is installed this is configured automatically and should not be modified.

    "P": {
      . . .
      "MvcApplication": {
        . . .
        "LogoffUrl": "/YetaWF_Identity/LoginDirect/Logoff?NextUrl=",
        . . .

Application.P.StaticFiles.Duration

Defines how long static files served by the site are valid, by setting the HTTP response Cache-Control header (max-age). The Application.P.StaticFiles.Duration value is specified in minutes. This should be set to 0 for development systems so JavaScript and CSS files aren't cached. For production systems, 1 year (>= 525,600 minutes) should be specified. All static files carry some form of version identifier (or cache buster), so they are still downloaded when new files are available.

Application.P.YetaWF_Identity.BACKDOOR-IS-WIDE-OPEN

Overrides all authentication and is only used when things go horribly wrong, see Panic Mode - I Can't Log In.

This setting defaults to false.

    "P": {
      . . .
      "YetaWF_Identity": {
        . . .
        "BACKDOOR-IS-WIDE-OPEN": true,
        . . .