ASP.NET Output Cache Provider

The Scaleout.AspNet.OutputCache NuGet package provides an output cache provider for use with ScaleOut Software’s in-memory data grid products.

(This provider is for ASP.NET applications running on the traditional .NET 4.x Framework. For ASP.NET Core caching support, use the Scaleout.AspNetCore package.)

Background

This is a new, alternative ASP.NET output cache provider that is different from the original provider that ships in the ScaleOut Product Suite’s installer. This new provider offers the following benefits:

  • No need to install/configure ScaleOut’s remote client libraries.

  • Configuration is specified entirely through the application’s web.config file.

  • Built on top of ScaleOut’s new Scaleout.Client library.

Prerequisites

  • One or more instances of the ScaleOut StateServer service (either local or remote).

  • .NET Framework 4.6.2 or higher.

Configuration

Install this NuGet package and its dependencies:

Install-Package Scaleout.AspNet.OutputCache

Modify the outputCache element in your app’s web.config file to use the Scaleout.AspNet.OutputCache provider. For example:

<caching>
  <outputCache defaultProvider="ScaleoutOutputCacheProvider">
    <providers>
      <add name="ScaleoutOutputCacheProvider"
           type="Scaleout.AspNet.OutputCache.ScaleoutOutputCacheProvider"
           connectionString="bootstrapGateways=192.168.1.42:721,192.168.1.43:721;maxRequestRetries=2;eventConnectionCount=4"
           namespace="MyOutputCacheNamespace"
           clientCacheType="LRU"
           clientCacheCapacity="100"
           throwOnError="false"
           accessTimeoutMilliseconds="250" />
    </providers>
  </outputCache>
</caching>

Provider Settings

The following configuration attributes in the example above are specific to the ScaleOut output cache provider:

connectionString

String containing information for connecting to ScaleOut service, as described in the Connecting to a ScaleOut Data Grid topic.

namespace

Optional. Specifies the cache namespace that the ScaleOut service will use for storing output cache entries. If omitted, the application path in the web server is used as the basis for the cache name.

clientCacheType

Optional. The type of eviction strategy used by the library’s in-process client cache. The default is “LRU”, indicating that the client cache size is limited to a count of recently-accessed output cache entries, as specified by the clientCacheCapacity value. If “LRU-MaxMemory” is used, the size of the client cache size is determined by memory usage instead of a simple count; the clientCacheCapacity value indicates the client cache’s memory limit in this mode (specified in megabytes).

clientCacheCapacity

Optional. The size of the library’s in-process client cache, expressed either as a count or a memory limit (in MB), depending on the clientCacheType value. The default value is 100 output cache entries (or 100 megabytes, if clientCacheType is “LRU-MaxMemory”).

throwOnError

Configures whether this provider will throw an exception if a connectivity error occurs while accessing the ScaleOut service or if the provider will report an output cache miss to the ASP.NET request pipeline.

accessTimeoutMilliseconds

Specifies the maximum time (in milliseconds) that the Output Cache Provider will wait to receive a response from the ScaleOut service. If the timeout is elapsed, the provider will inform the ASP.NET pipeline that the output cache entry does not exist, and the resulting “cache miss” will cause ASP.NET to execute the full request handler instead. A value of 0 will cause the provider to wait indefinitely, causing the web request to be blocked until a result is returned.

Setting a timeout can be useful when re-running your handler is preferable to waiting for a result (or an error). For example, it can take several seconds for an error to occur if the ScaleOut data grid becomes unreachable, so you may choose to use this attribute to bypass output caching instead of waiting. A value of 250 milliseconds is a reasonable timeout for most situations—it is more than enough time for almost any ScaleOut access but allows you to fall back to your request handler to maintain site availability in case of a slowdown or a problem.

Alternative Connection String Locations

To specify a connection string through a different mechanism than the connectionString attribute described above, remove the connectionString attribute and replace it with one of the following alternatives:

connectionStringEnvironmentVariable

The name of a system environment variable containing the ScaleOut connection string.

connectionStringAppSetting

The name of an entry in a config file’s appSettings section that contains the ScaleOut connection string.

connectionStringElement

The name of an entry in a config file’s connectionStrings section that contains the ScaleOut connection string. The specified entry under the connectionStrings section does not need to have its providerName attribute set if this location is used.

The value that is referenced in any of these locations must be a valid connection string as described in Connecting to a ScaleOut Data Grid.

Troubleshooting Configuration Errors

When an error occurs in an ASP.NET application, the standard error page (often called the “Yellow Screen of Death”, or YSOD) typically provides useful troubleshooting details such as exception information and a stack trace. However, ASP.NET does not provide this detailed information when an exception is thrown from a output cache provider. Instead, the YSOD simply states that a configuration error occurred and highlights the provider that is responsible for the problem.

To see the full stack and exception details when the ScaleOut provider cannot start up due to a configuration/connectivity problem, open the Windows Event Viewer and check the Application Event Log; the full exception will be logged as a Warning entry.