Azure Cache for Redis の ASP.NET 出力キャッシュ プロバイダーASP.NET Output Cache Provider for Azure Cache for Redis

Redis 出力キャッシュ プロバイダーは、出力キャッシュ データ用のプロセス外ストレージ メカニズムです。The Redis Output Cache Provider is an out-of-process storage mechanism for output cache data. このデータは、完全な HTTP 応答専用です (ページ出力キャッシュ)。This data is specifically for full HTTP responses (page output caching). プロバイダーは、ASP.NET 4 で導入された新しい出力キャッシュ プロバイダー拡張機能ポイントに接続します。The provider plugs into the new output cache provider extensibility point that was introduced in ASP.NET 4.

Redis 出力キャッシュ プロバイダーを使用するには、まず対象のキャッシュを構成し、Redis 出力キャッシュ プロバイダー NuGet パッケージを使用して ASP.NET アプリケーションを構成します。To use the Redis Output Cache Provider, first configure your cache, and then configure your ASP.NET application using the Redis Output Cache Provider NuGet package. このトピックでは、Redis 出力キャッシュ プロバイダーを使用するようにアプリケーションを構成する手順について説明します。This topic provides guidance on configuring your application to use the Redis Output Cache Provider. Azure Cache for Redis インスタンスを作成および構成する方法の詳細については、キャッシュの作成に関するページを参照してください。For more information about creating and configuring an Azure Cache for Redis instance, see Create a cache.

ASP.NET ページ出力をキャッシュに格納するStore ASP.NET page output in the cache

Visual Studio で Azure Cache for Redis Session State NuGet パッケージを使用してクライアント アプリケーションを構成するには、 [ツール] メニューで [NuGet パッケージ マネージャー][パッケージ マネージャー コンソール] の順にクリックします。To configure a client application in Visual Studio using the Azure Cache for Redis Session State NuGet package, click NuGet Package Manager, Package Manager Console from the Tools menu.

[Package Manager Console] ウィンドウで、次のコマンドを実行します。Run the following command from the Package Manager Console window.

Install-Package Microsoft.Web.RedisOutputCacheProvider

Redis 出力キャッシュ プロバイダー NuGet パッケージは、StackExchange.Redis.StrongName パッケージに依存します。The Redis Output Cache Provider NuGet package has a dependency on the StackExchange.Redis.StrongName package. StackExchange.Redis.StrongName パッケージは、プロジェクト内に存在しなければインストールされます。If the StackExchange.Redis.StrongName package is not present in your project, it is installed. Redis Output Cache Provider NuGet パッケージについて詳しくは、RedisOutputCacheProvider NuGet ページを参照してください。For more information about the Redis Output Cache Provider NuGet package, see the RedisOutputCacheProvider NuGet page.

注意

厳密な名前を持つ StackExchange.Redis.StrongName パッケージ以外に、厳密な名前を持たない StackExchange.Redis バージョンもあります。In addition to the strong-named StackExchange.Redis.StrongName package, there is also the StackExchange.Redis non-strong-named version. プロジェクトで厳密な名前を持たないバージョンの StackExchange.Redis を使っている場合は、それをアンインストールする必要があります。そうしないと、プロジェクトで名前の競合が発生します。If your project is using the non-strong-named StackExchange.Redis version you must uninstall it; otherwise, you will experience naming conflicts in your project. これらのパッケージの詳細については、.NET キャッシュ クライアントの構成に関するトピックを参照してください。For more information about these packages, see Configure .NET cache clients.

NuGet パッケージがダウンロードされ、必要なアセンブリ参照が追加されて、次のセクションが web.config ファイルに追加されます。The NuGet package downloads and adds the required assembly references and adds the following section into your web.config file. このセクションには、Redis 出力キャッシュ プロバイダーを使うために ASP.NET アプリケーションに必要な構成が含まれます。This section contains the required configuration for your ASP.NET application to use the Redis Output Cache Provider.

<caching>
  <outputCache defaultProvider="MyRedisOutputCache">
    <providers>
      <add name="MyRedisOutputCache" type="Microsoft.Web.Redis.RedisOutputCacheProvider"
           host=""
           accessKey=""
           ssl="true" />
    </providers>
  </outputCache>
</caching>

属性の構成には、Microsoft Azure ポータルのキャッシュ ブレードの値を使用してください。その他の値は適宜構成します。Configure the attributes with the values from your cache blade in the Microsoft Azure portal, and configure the other values as desired. キャッシュのプロパティにアクセスする方法については、「Configure Azure Cache for Redis settings (Azure Cache for Redis の設定を構成する)」を参照してください。For instructions on accessing your cache properties, see Configure Azure Cache for Redis settings.

AttributeAttribute TypeType 既定値Default 説明Description
hosthost stringstring "localhost""localhost" Redis サーバーの IP アドレスまたはホスト名The Redis server IP address or host name
portport 正の整数positive integer 6379 (非 SSL)6379 (non-SSL)
6380 (SSL)6380 (SSL)
Redis サーバー ポートRedis server port
accessKeyaccessKey stringstring """" Redis 認証が有効になっている場合は、Redis サーバーのパスワード。Redis server password when Redis authorization is enabled. 既定では、値は空の文字列です。これは、セッション状態プロバイダーが Redis サーバーに接続するときにパスワードを使用しないことを意味します。The value is empty string by default, which means the session state provider won’t use any password when connecting to Redis server. Redis サーバーが Azure Redis Cache のようなパブリックにアクセス可能なネットワークにある場合は、セキュリティを強化するために必ず Redis 認証を有効にして、安全なパスワードを提供してください。If your Redis server is in a publicly accessible network like Azure Redis Cache, be sure to enable Redis authorization to improve security, and provide a secure password.
sslssl ブール値boolean falsefalse Redis サーバーに SSL 経由で接続するかどうか。Whether to connect to Redis server via SSL. Redis は初期状態では SSL をサポートしていないため、この値は既定では false です。This value is false by default because Redis doesn’t support SSL out of the box. 初期状態で SSL をサポートする Azure Redis Cache を使用している場合は、セキュリティを強化するためにこれを必ず true に設定してください。If you are using Azure Redis Cache which supports SSL out of the box, be sure to set this to true to improve security.

既定では、新しいキャッシュに対して非 SSL ポートは無効になっています。The non-SSL port is disabled by default for new caches. SSL ポートを使用するには、この設定に true を指定します。Specify true for this setting to use the SSL port. 非 SSL ポートの有効化の詳細については、キャッシュの構成に関するトピックの「アクセス ポート」セクションを参照してください。For more information about enabling the non-SSL port, see the Access Ports section in the Configure a cache topic.
databaseIdNumberdatabaseIdNumber 正の整数positive integer 00 この属性は、web.config または AppSettings でのみ指定できます。This attribute can be specified only through either web.config or AppSettings.

使用する Redis データベースを指定します。Specify which Redis database to use.
connectionTimeoutInMillisecondsconnectionTimeoutInMilliseconds 正の整数positive integer StackExchange.Redis によって提供されますProvided by StackExchange.Redis StackExchange.Redis.ConnectionMultiplexer の作成時に ConnectTimeout を設定するために使用されます。Used to set ConnectTimeout when creating StackExchange.Redis.ConnectionMultiplexer.
operationTimeoutInMillisecondsoperationTimeoutInMilliseconds 正の整数positive integer StackExchange.Redis によって提供されますProvided by StackExchange.Redis StackExchange.Redis.ConnectionMultiplexer の作成時に SyncTimeout を設定するために使用されます。Used to set SyncTimeout when creating StackExchange.Redis.ConnectionMultiplexer.
connectionString (有効な StackExchange.Redis 接続文字列)connectionString (Valid StackExchange.Redis connection string) stringstring 該当なしn/a AppSettings または web.config へのパラメーター参照、または有効な StackExchange.Redis 接続文字列。Either a parameter reference to AppSettings or web.config, or else a valid StackExchange.Redis connection string. この属性は、hostportaccessKeyssl、およびその他の StackExchange.Redis 属性の値を指定できます。This attribute can provide values for host, port, accessKey, ssl, and other StackExchange.Redis attributes. connectionString の詳細については、「属性に関する注意事項」セクションの「connectionString の設定」を参照してください。For a closer look at connectionString, see Setting connectionString in the Attribute notes section.
settingsClassNamesettingsClassName
settingsMethodNamesettingsMethodName
stringstring
stringstring
該当なしn/a これらの属性は、web.config または AppSettings でのみ指定できます。These attributes can be specified only through either web.config or AppSettings.

これらの属性を使用して、接続文字列を指定します。Use these attributes to provide a connection string. settingsClassName は、settingsMethodName で指定されたメソッドを含むアセンブリ修飾クラス名である必要があります。settingsClassName should be an assembly qualified class name that contains the method specified by settingsMethodName.

settingsMethodName で指定するメソッドは、戻り値の型が string の public、static、および void (パラメーターを取らない) である必要があります。The method specified by settingsMethodName should be public, static, and void (not take any parameters), with a return type of string. このメソッドは、実際の接続文字列を返します。This method returns the actual connection string.
loggingClassNameloggingClassName
loggingMethodNameloggingMethodName
stringstring
stringstring
該当なしn/a これらの属性は、web.config または AppSettings でのみ指定できます。These attributes can be specified only through either web.config or AppSettings.

これらの属性を使用して、セッション状態/出力キャッシュからのログと StackExchange.Redis からのログを提供することにより、アプリケーションをデバッグします。Use these attributes to debug your application by providing logs from Session State/Output Cache along with logs from StackExchange.Redis. loggingClassName は、loggingMethodName で指定されたメソッドを含むアセンブリ修飾クラス名である必要があります。loggingClassName should be an assembly qualified class name that contains the method specified by loggingMethodName.

loggingMethodName で指定するメソッドは、戻り値の型が System.IO.TextWriter の public、static、および void (パラメーターを取らない) である必要があります。The method specified by loggingMethodName should be public, static, and void (not take any parameters), with a return type of System.IO.TextWriter.
applicationNameapplicationName stringstring 現在のプロセスのモジュール名または "/"The module name of the current process or "/" SessionStateProvider のみSessionStateProvider only
この属性は、web.config または AppSettings でのみ指定できます。This attribute can be specified only through either web.config or AppSettings.

Redis Cache で使用するアプリ名プレフィックス。The app name prefix to use in Redis cache. お客様は、異なる目的で同じ Redis Cache を使用できます。The customer may use the same Redis cache for different purposes. セッション キーが競合しないようにするために、アプリケーション名をプレフィックスとして付けることができます。To insure that the session keys do not collide, it can be prefixed with the application name.
throwOnErrorthrowOnError ブール値boolean truetrue SessionStateProvider のみSessionStateProvider only
この属性は、web.config または AppSettings でのみ指定できます。This attribute can be specified only through either web.config or AppSettings.

エラーが発生したときに例外をスローするかどうか。Whether to throw an exception when an error occurs.

throwOnError の詳細については、「属性に関する注意事項」セクションの「throwOnError に関する注意事項」を参照してください。For more about throwOnError, see Notes on throwOnError in the Attribute notes section.
>Microsoft.Web.Redis.RedisSessionStateProvider.LastException>Microsoft.Web.Redis.RedisSessionStateProvider.LastException.
retryTimeoutInMillisecondsretryTimeoutInMilliseconds 正の整数positive integer 50005000 SessionStateProvider のみSessionStateProvider only
この属性は、web.config または AppSettings でのみ指定できます。This attribute can be specified only through either web.config or AppSettings.

操作が失敗したときに再試行する時間の長さ。How long to retry when an operation fails. この値が operationTimeoutInMilliseconds より小さい場合、プロバイダーは再試行しません。If this value is less than operationTimeoutInMilliseconds, the provider will not retry.

retryTimeoutInMilliseconds の詳細については、「属性に関する注意事項」セクションの「retryTimeoutInMilliseconds に関する注意事項」を参照してください。For more about retryTimeoutInMilliseconds, see Notes on retryTimeoutInMilliseconds in the Attribute notes section.
redisSerializerTyperedisSerializerType stringstring 該当なしn/a Microsoft.Web.Redis.ISerializerSpecifies the assembly qualified type name of a class that implements Microsoft.Web.Redis. を実装し、値をシリアル化および逆シリアル化するカスタム ロジックを含むクラスのアセンブリ修飾型名を指定します。ISerializer and that contains the custom logic to serialize and deserialize the values. 詳細については、「属性に関する注意事項」セクションの「redisSerializerType について」を参照してください。For more information, see About redisSerializerType in the Attribute notes section.

属性に関する注意事項Attribute notes

connectionString の設定Setting connectionString

connectionString の値は、AppSettings から実際の接続文字列 (そのような文字列が AppSettings に存在する場合) をフェッチするためのキーとして使用されます。The value of connectionString is used as key to fetch the actual connection string from AppSettings, if such a string exists in AppSettings. AppSettings 内に見つからない場合、connectionString の値は、web.config ConnectionString セクション (そのセクションが存在する場合) から実際の接続文字列をフェッチするためのキーとして使用されます。If not found inside AppSettings, the value of connectionString will be used as key to fetch actual connection string from the web.config ConnectionString section, if that section exists. 接続文字列が AppSettings または web.config ConnectionString セクションに存在しない場合は、StackExchange.Redis.ConnectionMultiplexer の作成時に、connectionString のリテラル値が接続文字列として使用されます。If the connection string does not exists in AppSettings or the web.config ConnectionString section, the literal value of connectionString will be used as the connection string when creating StackExchange.Redis.ConnectionMultiplexer.

次の例は、connectionString の使用方法を示しています。The following examples illustrate how connectionString is used.

例 1Example 1

<connectionStrings>
    <add name="MyRedisConnectionString" connectionString="mycache.redis.cache.windows.net:6380,password=actual access key,ssl=True,abortConnect=False" />
</connectionStrings>

web.config では、実際の値の代わりに上記のキーをパラメーター値として使用します。In web.config, use above key as parameter value instead of actual value.

<sessionState mode="Custom" customProvider="MySessionStateStore">
    <providers>
        <add type = "Microsoft.Web.Redis.RedisSessionStateProvide"
             name = "MySessionStateStore"
             connectionString = "MyRedisConnectionString"/>
    </providers>
</sessionState>

例 2Example 2

<appSettings>
    <add key="MyRedisConnectionString" value="mycache.redis.cache.windows.net:6380,password=actual access key,ssl=True,abortConnect=False" />
</appSettings>

web.config では、実際の値の代わりに上記のキーをパラメーター値として使用します。In web.config, use above key as parameter value instead of actual value.

<sessionState mode="Custom" customProvider="MySessionStateStore">
    <providers>
        <add type = "Microsoft.Web.Redis.RedisSessionStateProvide"
             name = "MySessionStateStore"
             connectionString = "MyRedisConnectionString"/>
    </providers>
</sessionState>

例 3Example 3

<sessionState mode="Custom" customProvider="MySessionStateStore">
    <providers>
        <add type = "Microsoft.Web.Redis.RedisSessionStateProvide"
             name = "MySessionStateStore"
             connectionString = "mycache.redis.cache.windows.net:6380,password=actual access key,ssl=True,abortConnect=False"/>
    </providers>
</sessionState>

throwOnError に関する注意事項Notes on throwOnError

現在、セッション操作中にエラーが発生した場合、セッション状態プロバイダーは例外をスローします。Currently, if an error occurs during a session operation, the session state provider will throw an exception. これにより、アプリケーションがシャットダウンされます。This shuts down the application.

この動作は、既存の ASP.NET セッション状態プロバイダー ユーザーの期待をサポートしながら、必要に応じて例外に対処する機能も提供するように変更されています。This behavior has been modified in a way that supports the expectations of existing ASP.NET session state provider users while also providing the ability to act on exceptions, if desired. 既定の動作では、エラーが発生すると引き続き例外がスローされます。これは他の ASP.NET セッション状態プロバイダーと同じです。既存のコードは以前と同じように動作するはずです。The default behavior still throws an exception when an error occurs, consistent with other ASP.NET session state providers; existing code should work the same as before.

throwOnErrorfalse に設定すると、エラーが発生したときに例外をスローするのではなく、何も行われずに失敗します。If you set throwOnError to false, then instead of throwing an exception when an error occurs, it will fail silently. エラーが発生したかどうかを確認し、発生した場合に例外を確認するには、静的プロパティ Microsoft.Web.Redis.RedisSessionStateProvider.LastException を調べてください。To see if there was an error and, if so, discover what the exception was, check the static property Microsoft.Web.Redis.RedisSessionStateProvider.LastException.

retryTimeoutInMilliseconds に関する注意事項Notes on retryTimeoutInMilliseconds

これにより、再試行ロジックが提供され、一部のセッション操作がネットワーク障害などの理由で失敗時に再試行する必要がある場合のケースが簡略化されます。また、再試行タイムアウトを制御したり、再試行を完全に除外したりすることもできます。This provides some retry logic to simplify the case where some session operation should retry on failure because of things like network glitch, while also allowing you to control the retry timeout or opt out of retry entirely.

retryTimeoutInMilliseconds を 2000 などの数値に設定すると、セッション操作が失敗したときに、2000 ミリ秒間再試行されてからそれがエラーとして扱われます。If you set retryTimeoutInMilliseconds to a number, for example 2000, then when a session operation fails, it will retry for 2000 milliseconds before treating it as an error. そのため、セッション状態プロバイダーにこの再試行ロジックを適用させるには、タイムアウトを構成するだけで済みます。So to have the session state provider to apply this retry logic, just configure the timeout. 最初の再試行は 20 ミリ秒後に行われますが、ネットワーク障害が発生したときには、ほとんどの場合、これで十分です。The first retry will happen after 20 milliseconds, which is sufficient in most cases when a network glitch happens. その後、タイムアウトするまで、1 秒ごとに再試行されます。タイムアウトの直後に、タイムアウトを (最大でも) 1 秒短縮しないようにするためにもう一度試行されます。After that, it will retry every second until it times out. Right after the time out, it will retry one more time to make sure that it won’t cut off the timeout by (at most) one second.

再試行が不要と思われる場合 (たとえば、Redis サーバーをアプリケーションと同じマシンで実行している場合)、または再試行ロジックを自分で処理する場合は、retryTimeoutInMilliseconds を 0 に設定します。If you don’t think you need retry (for example, when you are running the Redis server on the same machine as your application) or if you want to handle the retry logic yourself, set retryTimeoutInMilliseconds to 0.

redisSerializerType についてAbout redisSerializerType

既定では、Redis に値を格納するためのシリアル化は、BinaryFormatter クラスが提供するバイナリ形式で行われます。By default, the serialization to store the values on Redis is done in a binary format provided by the BinaryFormatter class. Microsoft.Web.Redis.ISerializer を実装し、値をシリアル化および逆シリアル化するカスタム ロジックを持つクラスのアセンブリ修飾型名を指定するには、redisSerializerType を使用します。Use redisSerializerType to specify the assembly qualified type name of a class that implements Microsoft.Web.Redis.ISerializer and has the custom logic to serialize and deserialize the values. 例として、JSON.NET を使用した JSON シリアライザー クラスを次に示します。For example, here is a Json serializer class using JSON.NET:

namespace MyCompany.Redis
{
    public class JsonSerializer : ISerializer
    {
        private static JsonSerializerSettings _settings = new JsonSerializerSettings() { TypeNameHandling = TypeNameHandling.All };

        public byte[] Serialize(object data)
        {
            return Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(data, _settings));
        }

        public object Deserialize(byte[] data)
        {
            if (data == null)6t6
            {
                return null;
            }
            return JsonConvert.DeserializeObject(Encoding.UTF8.GetString(data), _settings);
        }
    }
}

このクラスが MyCompanyDll という名前のアセンブリで定義されているとすると、それを使用するようにパラメーター redisSerializerType を設定できます。Assuming this class is defined in an assembly with name MyCompanyDll, you can set the parameter redisSerializerType to use it:

<sessionState mode="Custom" customProvider="MySessionStateStore">
    <providers>
        <add type = "Microsoft.Web.Redis.RedisSessionStateProvider"
             name = "MySessionStateStore"
             redisSerializerType = "MyCompany.Redis.JsonSerializer,MyCompanyDll"
             ... />
    </providers>
</sessionState>

出力キャッシュ ディレクティブOutput cache directive

出力をキャッシュする各ページに、OutputCache ディレクティブを追加します。Add an OutputCache directive to each page for which you wish to cache the output.

<%@ OutputCache Duration="60" VaryByParam="*" %>

前の例では、キャッシュされたページ データが 60 秒間キャッシュに保持され、パラメーターの組み合わせごとに異なるバージョンのページがキャッシュされます。In the previous example, the cached page data remains in the cache for 60 seconds, and a different version of the page is cached for each parameter combination. OutputCache ディレクティブの詳細については、「 @OutputCacheに関するページを参照してください。For more information about the OutputCache directive, see @OutputCache.

ここまでの手順を実行すると、アプリケーションは Redis 出力キャッシュ プロバイダーを使用するように構成されます。Once these steps are performed, your application is configured to use the Redis Output Cache Provider.

次の手順Next steps

ASP.NET Session State Provider for Azure Cache for Redis (Azure Cache for Redis の ASP.NET セッション状態プロバイダー)」を参照してください。Check out the ASP.NET Session State Provider for Azure Cache for Redis.