YetaWF.Caching Package Documentation

Display
Print

YetaWF.Caching Package

The YetaWF.Caching assembly/package implements the following low-level data providers:

  • File and folder I/O
  • Caching
  • Locking
  • PubSub Messaging

Applications do not access the low-level data providers in this package directly. Caching, locking and publish/subscribe services provided by YetaWF.Core.IO.Caching and file system services provided by YetaWF.Core.IO.FileSystem, YetaWF.Core.IO.DataFilesProvider and YetaWF.Core.IO.FileIO<TObj> should be used instead.

Depending on AppSettings.json settings, low-level data providers for single- or multi-instance sites are used.

Single-Instance Sites

A single-instance site is one single instance of the site, usually running in IIS or Docker. This is the typical use case for small to mid-size sites.

Multi-Instance Sites (Web Farm, Web Garden)

A multi-instance site runs multiple instances of the site in one instance of IIS/Docker on one server (web garden) or on multiple IIS/Docker instances on multiple servers (web farm). For multi-instance sites, Redis or SQL is used to implement caching services. Locking services use files or Redis to implement resource locking.

Multiple instances of a YetaWF site are rarely needed unless your site needs the utmost in availability and scalability. This is only accomplished by running multiple instances of the site on multiple servers in a web farm. Running multiple site in a web garden configuration (i.e., on one server with multiple instances in IIS/Docker) does not provide the availability, nor does it scale well as still only one server does all the work.

Running a web farm is not trivial, and you'll need to set up load balancers (not covered here). For caching/locking you'll need either SQL or Redis. For SQL it is sufficient to create a database and set the connection strings in AppSettings.json. YetaWF will create the necessary tables during initialization. For better performance, Redis is recommended. For information about setting up a Redis server see https://redis.io/.

When starting up the very first node of a multi-instance site, an empty file "FirstNode.txt" must be added to the ./Website folder. This is absolutely crucial to insure proper initialization of the site as a multi-instance site. Additional instances can then simply be started up (or shut down) at any time. Even the first node that was started can be recycled at any time. The first node that was started has no special attributes that require it to remain running.

When making certain Site Settings changes that would affect all sites, these may not take effect until the entire site is restarted (all nodes) and a first node is started with an empty file "FirstNode.txt". Very few actions require a restart. For example, changing the domain name or the CDN Url would require a full restart. Adding/changing pages or module content never requires a restart.

Admin > Dashboard > Audit Information (standard YetaWF site) can be used to determine whether a restart is pending.

AppSettings.json

AppSettings.json uses the following section to configure the YetaWF.Caching package:

{
  "Application": {
    "P": {
      "YetaWF_Caching": {
        "Distributed": {true|false},
        "CacheProvider": {"SQL"|"Redis"|"Local"},
        "LockProvider": {"File"|"Redis"},
        "PubSubProvider": {"File"|"Redis"},

        "RedisCacheConfig": "...your config...localhost:6379",
        "RedisLockConfig": "...your config...localhost:6379",
        "RedisKeyPrefix": "...some key prefix... _",
        "RedisPubSubConfig": "...your config...localhost:6379",
        "RedisPubSubPrefix":  "...some key prefix... _",

        "SQLDbo": "dbo",
        "SQLConnect": "Data Source=...datasource...;Initial Catalog=...catalog...;User ID=..userid...;Password=...password...",

        "LockFolder": "..path to folder where locks are recorded (within ./Website folder)..",

        "TempRootFolder": "..path to a folder for temporary files..",

        "SmallObjectCacheDuration": { 0 | -1 | n }
      },
    }
  }
}
ArgumentDescription
DistributedDefines whether a single- or multi-instance site is used. If Distributed is set to false, all caching properties (CacheProvider, RedisCacheConfig, SQLDbo, SQLConnect) are ignored and local caching is used.
CacheProviderDefines whether SQL or Redis is used for caching services. If SQL is used, SQLDbo and SQLConnect must also be defined. For Redis, RedisCacheConfig must also be defined.
LockProviderDefines whether Local (local caching), File (file system) or Redis is used to implement locking services. For File, LockFolder must also be defined. For Redis, RedisLockConfig must also be defined. When using local caching, there can be only one instance of a site as there is no shared caching.
PubSubProviderDefines whether a publish/subscribe service is used. Redis is the only available option. RedisPubSubConfig must also be defined. If PubSubProvider is omitted, the publish/subscribe service is not available. It is not currently used by YetaWF but is available for custom development.
RedisCacheConfigDefines the Redis server when CacheProvider is set to Redis. The same Redis server can be used for caching, locking and pubsub services. The default is localhost:6379.
RedisLockConfigDefines the Redis server when LockProvider is set to Redis. The same Redis server can be used for caching, locking and pubsub services. The default is localhost:6379.
RedisKeyPrefixDefines a string that is added to every data key used with the Redis server (as a prefix). Must be the same for all instances of a multi-instance site.
RedisPubSubPrefixDefines a string that is added to every publish/subscribe key used with the Redis server (as a prefix). Must be the same for all instances of a multi-instance site.
SQLDboDefines the database owner when CacheProvider is set to SQL. If not is specified, the Application.P.Default.SQLDbo setting is used.
SQLConnectDefines the SQL connection string when CacheProvider is set to SQL. If not is specified, the Application.P.Default.SQLConnect setting is used.
LockFolderDefines the folder where locked resources are tracked when LockProvider is set to File. This folder must be the same for all site instances and must be shared. The folder may be external to the ./Website folder. The default is ./Website/Data/DataFolder/YetaWF_Caching/__LOCKS.
TempRootFolderDefines the folder where the temporary file system is located. This folder is unique to each site instance and must not be shared. The folder may be located external to the ./Website folder. The default is ./Website/Data/DataFolder/YetaWF_Caching/TempFiles. This folder is emptied during a site restart.
SmallObjectCacheDurationDefines the cache expiration time for the small objects cache provider (YetaWF.Core.IO.Caching). 0 no expiration, -1 don't cache, any other value is the cache duration in minutes. If an object is older, it is removed. The default in debug builds is don't cache (-1). In release builds the default is no expiration (0).

AppSettings.json Examples

Multi-Instance Site (SQL)
{
  "Application": {
    "P": {
      "YetaWF_Caching": {
        "Distributed": true,
        "CacheProvider": "SQL",
        "LockProvider": "File",
        "SQLDbo": "dbo",
        "SQLConnect": "Data Source=...datasource...;Initial Catalog=...catalog...;User ID=..userid...;Password=...password..."
      },
    }
  }
}
Multi-Instance Site (Redis)
{
  "Application": {
    "P": {
      "YetaWF_Caching": {
        "Distributed": true,
        "CacheProvider": "Redis",
        "LockProvider": "Redis",
        "RedisCacheConfig": "localhost:6379",
        "RedisLockConfig": "localhost:6379",
      },
    }
  }
}
Single Instance Site

A single-instance site does not use distributed caching or a shared file systems and offers the best performance.

{
  "Application": {
    "P": {
      "YetaWF_Caching": {
        "Distributed": false,
      }
    }
  }
}

See Also YetaWF.Core