ASP.NET-Ausgabecacheanbieter für Azure Cache for Redis

Der Redis-Ausgabecacheanbieter ist ein prozessunabhängiger Speichermechanismus für Ausgabecachedaten. Diese Daten sind für vollständige HTTP-Antworten bestimmt (Zwischenspeichern von Seitenausgaben). Der Anbieter wird zum neuen Erweiterungspunkt des Ausgabecacheanbieters hinzugefügt, der in ASP.NET 4 eingeführt wurde.

Informationen zu ASP.NET Core-Anwendungen finden Sie unter Middleware für die Ausgabezwischenspeicherung in ASP.NET Core.

Zum Verwenden des Redis-Ausgabecacheanbieters konfigurieren Sie zunächst den Cache. Danach konfigurieren Sie Ihre ASP.NET-Anwendung mithilfe des Redis-Ausgabecacheanbieter-NuGet-Pakets. Dieser Artikel enthält eine Anleitung darüber, wie Sie Ihre Anwendung für die Verwendung des Redis-Ausgabecacheanbieters konfigurieren.

Speichern der ASP.NET Core-Seitenausgabe in Redis

Eine vollständige Featurespezifikation finden Sie unter Ausgabezwischenspeicherung in ASP.NET Core.

Eine Beispielanwendung zur Veranschaulichung der Verwendung finden Sie unter .NET 8-Webanwendung mit Redis-Ausgabezwischenspeicherung und Azure OpenAI.

Speichern der ASP.NET-Seitenausgabe in Redis

Wählen Sie im Menü Extras im NuGet-Paket-Manager die Option Paket-Manager-Konsole zum Konfigurieren einer Clientanwendung in Visual Studio mit dem Azure Cache for Redis Session State NuGet-Paket.

Führen Sie im Fenster Package Manager Console den folgenden Befehl aus:

Install-Package Microsoft.Web.RedisOutputCacheProvider

Das NuGet-Paket für den Redis-Ausgabecacheanbieter weist eine Abhängigkeit zum Paket StackExchange.Redis auf. Wenn das Paket StackExchange.Redis in Ihrem Projekt nicht vorhanden ist, wird es installiert. Weitere Informationen zum Redis-Ausgabecacheanbieter-NuGet-Paket finden Sie auf der NuGet-Seite RedisOutputCacheProvider.

Mit dem heruntergeladenen NuGet-Paket werden die erforderlichen Assemblyverweise sowie der folgende Abschnitt in Ihrer Datei „web.config“ hinzugefügt. Dieser Abschnitt enthält die Konfiguration, die in Ihrer ASP.NET-Anwendung für die Verwendung des Redis-Ausgabecacheanbieters erforderlich ist.

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

Konfigurieren Sie die Attribute in der ersten Spalte mit den Werten aus Ihrem Cache im Microsoft Azure-Portal. Konfigurieren Sie außerdem die anderen von Ihnen gewünschten Werte. Anweisungen zum Zugreifen auf die Cacheeigenschaften finden Sie unter Konfigurieren von Azure Cache for Redis-Einstellungen.

attribute	type	Standard	Beschreibung
_host*	Zeichenfolge	„localhost“	IP-Adresse oder Hostname des Redis-Servers
port	Positive Ganzzahl	6379 (TLS-/SSL-fremd) 6380 (TLS/SSL) 10000 für Redis-Enterprise und Azure Managed Redis (Vorschau)	Redis-Serverport
accessKey	Zeichenfolge	""	Redis-Serverkennwort, wenn Redis-Autorisierung aktiviert ist. Der Wert ist standardmäßig eine leere Zeichenfolge und bedeutet, dass der Sitzungszustandsanbieter beim Herstellen einer Verbindung mit dem Redis-Server kein Kennwort verwendet. Wenn sich Ihr Redis-Server in einem öffentlich zugänglichen Netzwerk wie Azure Cache for Redis befindet, denken Sie daran, die Redis-Autorisierung zu aktivieren, um die Sicherheit zu erhöhen, und ein sicheres Kennwort anzugeben.
ssl	boolean	false	Gibt an, ob die Verbindung mit dem Redis-Server über TLS hergestellt werden soll. Dieser Wert ist standardmäßig auf false gestellt, da der TLS von Redis nicht standardmäßig unterstützt wird. Wenn Sie Azure Cache for Redis verwenden, das standardmäßig SSL unterstützt, sollten Sie diesen Wert auf „true“ setzen, um die Sicherheit zu erhöhen. Der TLS-fremde Port ist für neue Caches standardmäßig deaktiviert. Legen Sie diese Einstellung auf true fest, um den TLS-fremden Port zu verwenden. Weitere Informationen zum Aktivieren des TLS-fremden Ports finden Sie im Abschnitt Zugriffsports des Artikels Konfigurieren eines Caches.
databaseIdNumber	Positive Ganzzahl	0	Dieses Attribut kann nur entweder über „web.config“ oder über „appSettings“ angegeben werden. Geben Sie an, welche Redis-Datenbank verwendet werden soll.
connectionTimeoutInMilliseconds	Positive Ganzzahl	Wird von „StackExchange.Redis“ angegeben.	Wird zum Festlegen von ConnectTimeout verwendet, wenn „StackExchange.Redis.ConnectionMultiplexer“ erstellt wird.
operationTimeoutInMilliseconds	Positive Ganzzahl	Wird von „StackExchange.Redis“ angegeben.	Wird zum Festlegen von SyncTimeout verwendet, wenn „StackExchange.Redis.ConnectionMultiplexer“ erstellt wird.
connectionString (Gültige Verbindungszeichenfolge für „StackExchange.Redis“)	Zeichenfolge	Nicht zutreffend	Entweder ein Parameterverweis auf „appSettings“ oder auf „Web.config“ oder sonst eine gültige Verbindungszeichenfolge für „StackExchange.Redis“. Dieses Attribut kann die Werte für host, port, accessKey, ssl und andere Attribute von „StackExchange.Redis“ bereitstellen. Ausführlichere Informationen zu connectionString finden Sie unter Festlegen von „connectionString“ im Abschnitt Hinweise zu Attributen.
settingsClassName settingsMethodName	Zeichenfolge Zeichenfolge	Nicht zutreffend	Diese Attribute können nur entweder über „web.config“ oder über „appSettings“ angegeben werden. Verwenden Sie diese Attribute, um eine Verbindungszeichenfolge bereitzustellen. „_settingsClassName*“ sollte ein als Assembly qualifizierter Klassenname sein, der die von settingsMethodName angegebene Methode enthält. Die von settingsMethodName angegebene Methode sollte öffentlich, statisch und „void“ (keine Parameter akzeptieren) sein, und den Rückgabetyp string besitzen. Diese Methode gibt die tatsächliche Verbindungszeichenfolge zurück.
loggingClassName loggingMethodName	Zeichenfolge Zeichenfolge	Nicht zutreffend	Diese Attribute können nur entweder über „web.config“ oder über „appSettings“ angegeben werden. Verwenden Sie diese Attribute, um Ihre Anwendung zu debuggen, indem Sie Protokolle aus dem Sitzungszustands-/Ausgabecache zusammen mit Protokollen aus „StackExchange.Redis“ bereitstellen. loggingClassName sollte ein Assembly-qualifizierter Klassenname sein, der die von loggingMethodName angegebene Methode enthält. Die von loggingMethodName angegebene Methode sollte öffentlich, statisch und „void“ (keine Parameter akzeptieren) sein, und den Rückgabetyp System.IO.TextWriter besitzen.
applicationName	Zeichenfolge	Der Modulname des aktuellen Prozesses oder „/“	Nur SessionStateProvider Dieses Attribut kann nur entweder über „web.config“ oder über „appSettings“ angegeben werden. Das in Redis Cache zu verwendende App-Namenspräfix. Derselbe Redis-Cache kann für unterschiedliche Zwecke verwendet werden. Um sicherzustellen, dass bei den Sitzungsschlüsseln keine Konflikte auftreten, kann der Anwendungsname vorangestellt werden.
throwOnError	boolean	true	Nur SessionStateProvider Dieses Attribut kann nur entweder über „web.config“ oder über „appSettings“ angegeben werden. Ob eine Ausnahme ausgelöst werden soll, wenn ein Fehler auftritt. Weitere Informationen zu throwOnError finden Sie unter Hinweise zu throwOnError im Abschnitt Hinweise zu Attributen.
retryTimeoutInMilliseconds	Positive Ganzzahl	5.000	Nur SessionStateProvider Dieses Attribut kann nur entweder über „web.config“ oder über „appSettings“ angegeben werden. Wie lange wiederholt werden soll, wenn ein Vorgang fehlschlägt. Wenn dieser Wert kleiner als operationTimeoutInMilliseconds ist, wiederholt der Anbieter den Vorgang nicht. Weitere Informationen zu retryTimeoutInMilliseconds finden Sie unter Hinweise zu retryTimeoutInMilliseconds im Abschnitt Hinweise zu Attributen.
redisSerializerType	Zeichenfolge	Nicht zutreffend	Gibt den Assembly-qualifizierten Typnamen einer Klasse an, die „Microsoft.Web.Redis“ implementiert. Ein Serialisierungsprogramm das eine benutzerdefinierte Logik zum Serialisieren und Deserialisieren der Werte enthält. Weitere Informationen finden Sie unter Informationen zu redisSerializerType im Abschnitt Hinweise zu Attributen.

Hinweise zu Attributen

Festlegen von connectionString

Der Wert von connectionString wird als Schlüssel verwendet, um die tatsächliche Verbindungszeichenfolge von „AppSettings“ abzurufen, wenn solch eine Zeichenfolge in „AppSettings“ vorhanden ist. Wenn sie nicht in AppSettings gefunden wurde, wird der Wert von connectionString als Schlüssel verwendet, um die tatsächliche Verbindungszeichenfolge aus dem Abschnitt ConnectionString der Datei „web.config“ zu fetchen, sofern dieser Abschnitt vorhanden ist. Wenn die Verbindungszeichenfolge weder in AppSettings noch im Abschnitt ConnectionString von „web.config“ enthalten ist, wird der Literalwert von connectionString als Verbindungszeichenfolge verwendet, um den „StackExchange.Redis.ConnectionMultiplexer“ zu erstellen.

Die folgenden Beispiele veranschaulichen, wie connectionString verwendet wird.

Beispiel 1

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

Verwenden Sie in web.config anstelle des tatsächlichen Werts den Schlüssel als Parameterwert.

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

Beispiel 2

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

Verwenden Sie in web.config anstelle des tatsächlichen Werts den Schlüssel als Parameterwert.

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

Beispiel 3

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

Hinweise zu throwOnError

Zurzeit löst der Sitzungszustandsanbieter, wenn während eines Sitzungsvorgangs ein Fehler auftritt, eine Ausnahme aus. Durch das Auslösen der Ausnahme wird die Anwendung heruntergefahren.

Dieses Verhalten wurde an die Erwartungen der Benutzerinnen und Benutzer vorhandener ASP.NET-Sitzungszustandsanbieter angepasst. Es bietet Ihnen gleichzeitig die Möglichkeit, auf Ausnahmen zu reagieren. Beim Standardverhalten wird immer noch eine Ausnahme ausgelöst, wenn ein Fehler auftritt, der mit anderen ASP.NET-Sitzungsstatusanbietern konsistent ist. Ein vorhandener Code sollte genauso funktionieren wie zuvor.

Wenn Sie Einstellung throwOnError auf false festlegen, dann wird beim Auftreten eines Fehlers keine Ausnahme ausgelöst. Um festzustellen, ob ein Fehler aufgetreten ist, und wenn dies der Fall war, um die Ausnahme zu ermitteln, überprüfen Sie die statische Eigenschaft Microsoft.Web.Redis.RedisSessionStateProvider.LastException.

Hinweise zu retryTimeoutInMilliseconds

Die Einstellung retryTimeoutInMilliseconds bietet eine gewisse Logik, um den Fall zu vereinfachen, in dem ein Sitzungsvorgang bei einem Fehler aufgrund einer Netzwerkpanne oder eines anderen Vorgangs erneut versucht werden soll. Mit der Einstellung retryTimeoutInMilliseconds können Sie auch das Wiederholungs-Timeout steuern oder die Wiederholung vollständig abmelden.

Wenn Sie retryTimeoutInMilliseconds auf eine Zahl festlegen (z. B. 2.000) und bei einem Sitzungsvorgang ein Fehler auftritt, wird der Vorgang 2.000 ms lang wiederholt, bevor er als Fehler behandelt wird. Damit der Sitzungszustandsanbieter diese Wiederholungslogik anwendet, konfigurieren Sie lediglich das Timeout. Der erste Wiederholungsversuch erfolgt nach 20 Millisekunden, was in den meisten Fällen ausreichend ist, wenn eine Netzwerkstörung auftritt. Anschließend wird der Vorgang jede Sekunde wiederholt, bis das Timeout eintritt. Direkt nach dem Timeout erfolgt noch eine einzige Wiederholung, um sicherzustellen, dass das Timeout nicht um (höchstens um) eine Sekunde unterschritten wird.

Wenn Sie glauben, dass Sie die Wiederholung nicht benötigen oder wenn Sie die Wiederholungslogik selbst übernehmen möchten, setzen Sie die Einstellung retryTimeoutInMilliseconds auf 0. Wenn Sie beispielsweise den Redis-Server auf demselben Computer wie Ihre Anwendung ausführen, sollten Sie den Vorgang nicht wiederholen.

Informationen zu redisSerializerType

Die Serialisierung zum Speichern der Werte auf Redis erfolgt standardmäßig in einem Binärformat, das von der BinaryFormatter-Klasse bereitgestellt wird. Verwenden Sie redisSerializerType, um den Assembly-qualifizierten Typnamen einer Klasse anzugeben, die Microsoft.Web.Redis.ISerializer implementiert und die benutzerdefinierte Logik zum Serialisieren und Deserialisieren der Werte besitzt. Hier sehen Sie z. B. eine Json-Serialisierungsklasse, die JSON.NET verwendet:

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)
            {
                return null;
            }
            return JsonConvert.DeserializeObject(Encoding.UTF8.GetString(data), _settings);
        }
    }
}

Unter der Voraussetzung, dass diese Klasse in einer Assembly mit dem Namen MyCompanyDll definiert ist, können Sie den Parameter redisSerializerType festlegen, um sie zu verwenden:

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

OutputCache-Direktive

Fügen Sie jeder Seite, für die Sie die Ausgabe zwischenspeichern möchten, eine OutputCache-Direktive hinzu.

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

Im vorherigen Beispiel verbleiben die zwischengespeicherten Seitendaten 60 Sekunden lang im Cache. Für jede Parameterkombination wird eine andere Version der Seite zwischengespeichert. Weitere Informationen über die OutputCache-Direktive finden Sie unter @OutputCache.

Nach dem Abschluss dieser Schritte ist Ihre Anwendung für die Verwendung des Redis-Ausgabecacheanbieters konfiguriert.

Ausgabecacheanbieter von Drittanbieter

• NCache
• Apache Ignite

Zugehöriger Inhalt

Lesen Sie die Seite ASP.NET-Sitzungszustandsanbieter für Azure Cache for Redis.