Biblioteka hybridCache w programie ASP.NET Core
Ważne
Te informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.
W tym artykule wyjaśniono, jak skonfigurować bibliotekę HybridCache
i używać jej w aplikacji ASP.NET Core. Aby zapoznać się z wprowadzeniem do biblioteki, zobacz HybridCache
sekcję Buforowanie overview (Omówienie Buforowanie).
Pobieranie biblioteki
Zainstaluj pakiet Microsoft.Extensions.Caching.Hybrid
.
dotnet add package Microsoft.Extensions.Caching.Hybrid --prerelease
Rejestrowanie usługi
Dodaj usługę HybridCache
do kontenera wstrzykiwania zależności (DI), wywołując polecenie AddHybridCache
:
// Add services to the container.
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddAuthorization();
builder.Services.AddHybridCache();
Powyższy kod rejestruje usługę HybridCache
przy użyciu opcji domyślnych. Interfejs API rejestracji może również skonfigurować opcje i serializacji.
Pobieranie i przechowywanie wpisów pamięci podręcznej
Usługa HybridCache
udostępnia metodę z dwoma GetOrCreateAsync
przeciążeniami, przyjmując klucz i:
- Metoda fabryki.
- Stan i metoda fabryki.
Metoda używa klucza, aby spróbować pobrać obiekt z podstawowej pamięci podręcznej. Jeśli element nie zostanie znaleziony w podstawowej pamięci podręcznej (brakuje pamięci podręcznej), sprawdza pomocniczą pamięć podręczną, jeśli została skonfigurowana. Jeśli nie znajdzie tam danych (inna miss pamięci podręcznej), wywołuje metodę fabryki, aby pobrać obiekt ze źródła danych. Następnie przechowuje obiekt w pamięciach podręcznych podstawowych i pomocniczych. Metoda fabryki nigdy nie jest wywoływana, jeśli obiekt znajduje się w podstawowej lub pomocniczej pamięci podręcznej (trafieniu pamięci podręcznej).
HybridCache
Usługa zapewnia, że tylko jeden współbieżny obiekt wywołujący dla danego klucza wykonuje metodę fabryki, a wszystkie inne wywołujące oczekują na wynik tego wykonania. Przekazany element CancellationToken
reprezentuje GetOrCreateAsync
połączone anulowanie wszystkich współbieżnych wywołań.
Główne GetOrCreateAsync
przeciążenie
Przeciążenie bezstanowe GetOrCreateAsync
polecenia jest zalecane w przypadku większości scenariuszy. Kod do wywołania jest stosunkowo prosty. Oto przykład:
public class SomeService(HybridCache cache)
{
private HybridCache _cache = cache;
public async Task<string> GetSomeInfoAsync(string name, int id, CancellationToken token = default)
{
return await _cache.GetOrCreateAsync(
$"{name}-{id}", // Unique key to the cache entry
async cancel => await GetDataFromTheSourceAsync(name, id, cancel),
token: token
);
}
public async Task<string> GetDataFromTheSourceAsync(string name, int id, CancellationToken token)
{
string someInfo = $"someinfo-{name}-{id}";
return someInfo;
}
}
Alternatywne GetOrCreateAsync
przeciążenie
Alternatywne przeciążenie może zmniejszyć obciążenie związane z przechwyconymi zmiennymi i wywołaniami zwrotnymi dla poszczególnych wystąpień, ale kosztem bardziej złożonego kodu. W większości scenariuszy wzrost wydajności nie przewyższa złożoności kodu. Oto przykład, który używa alternatywnego przeciążenia:
public class SomeService(HybridCache cache)
{
private HybridCache _cache = cache;
public async Task<string> GetSomeInfoAsync(string name, int id, CancellationToken token = default)
{
return await _cache.GetOrCreateAsync(
$"{name}-{id}", // Unique key to the cache entry
(name, id, obj: this),
static async (state, token) =>
await state.obj.GetDataFromTheSourceAsync(state.name, state.id, token),
token: token
);
}
public async Task<string> GetDataFromTheSourceAsync(string name, int id, CancellationToken token)
{
string someInfo = $"someinfo-{name}-{id}";
return someInfo;
}
}
Metoda SetAsync
W wielu scenariuszach GetOrCreateAsync
jest jedynym wymaganym interfejsem API. Ale HybridCache
musi SetAsync
również przechowywać obiekt w pamięci podręcznej bez próby pobrania go najpierw.
Usuwanie niewyjaśniętych wpisów pamięci podręcznej
Gdy dane bazowe dla wpisów pamięci podręcznej zmienią się przed ich wygaśnięciem, możesz jawnie usunąć wpisy. Wpisy do usunięcia można określić za pomocą klucza. Po usunięciu wpisu zostanie on usunięty zarówno z pamięci podręcznej podstawowej, jak i pomocniczej.
Usuń według klucza
Następujące metody obsługują usuwanie wpisów pamięci podręcznej według klucza:
RemoveKeyAsync
RemoveKeysAsync
Uwaga: te zmiany zmienią się na RemoveByKeyAsync
i RemoveByKeysAsync
w przyszłości.
Opcje
Metody AddHybridCache
można użyć do skonfigurowania wartości domyślnych globalnych. W poniższym przykładzie pokazano, jak skonfigurować niektóre z dostępnych opcji:
// Add services to the container.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthorization();
builder.Services.AddHybridCache(options =>
{
options.MaximumPayloadBytes = 1024 * 1024;
options.MaximumKeyLength = 1024;
options.DefaultEntryOptions = new HybridCacheEntryOptions
{
Expiration = TimeSpan.FromMinutes(5),
LocalCacheExpiration = TimeSpan.FromMinutes(5)
};
});
Metoda GetOrCreateAsync
może również przesłonić HybridCacheEntryOptions
globalne wartości domyślne dla określonego wpisu pamięci podręcznej. Oto przykład:
public class SomeService(HybridCache cache)
{
private HybridCache _cache = cache;
public async Task<string> GetSomeInfoAsync(string name, int id, CancellationToken token = default)
{
var tags = new List<string> { "tag1", "tag2", "tag3" };
var entryOptions = new HybridCacheEntryOptions
{
Expiration = TimeSpan.FromMinutes(1),
LocalCacheExpiration = TimeSpan.FromMinutes(1)
};
return await _cache.GetOrCreateAsync(
$"{name}-{id}", // Unique key to the cache entry
async cancel => await GetDataFromTheSourceAsync(name, id, cancel),
entryOptions,
tags,
token: token
);
}
public async Task<string> GetDataFromTheSourceAsync(string name, int id, CancellationToken token)
{
string someInfo = $"someinfo-{name}-{id}";
return someInfo;
}
}
Aby uzyskać więcej informacji na temat opcji, zobacz kod źródłowy:
- HybridCacheOptions, klasa.
- HybridCacheEntryOptions, klasa.
Limity
Następujące właściwości HybridCacheOptions
umożliwiają skonfigurowanie limitów, które mają zastosowanie do wszystkich wpisów pamięci podręcznej:
- MaximumPayloadBytes — maksymalny rozmiar wpisu pamięci podręcznej. Wartość domyślna to 1 MB. Próby przechowywania wartości w tym rozmiarze są rejestrowane, a wartość nie jest przechowywana w pamięci podręcznej.
- MaximumKeyLength — maksymalna długość klucza pamięci podręcznej. Wartość domyślna to 1024 znaki. Próby przechowywania wartości w tym rozmiarze są rejestrowane, a wartość nie jest przechowywana w pamięci podręcznej.
Serializacja
Serializacja jest konfigurowana w ramach rejestrowania usługi z obsługą serializatorów specyficznych dla typu i uogólnionych za pośrednictwem WithSerializer
metod i .WithSerializerFactory
, w łańcuchu od wywołania AddHybridCache
. Domyślnie biblioteka obsługuje string
i wewnętrznie używa System.Text.Json
wszystkich innych elementów, ale można skonfigurować HybridCache
do używania narzędzia protobuf, xml byte[]
lub innych elementów.
Oto przykład konfigurowania usługi pod kątem używania serializatora protobuf.
Magazyn pamięci podręcznej
Domyślnie HybridCache
jest używany MemoryCache dla jego podstawowego magazynu pamięci podręcznej. Wpisy pamięci podręcznej są przechowywane w procesie, dlatego każdy serwer ma oddzielną pamięć podręczną, która zostanie utracona przy każdym ponownym uruchomieniu procesu serwera. W przypadku pomocniczego magazynu poza procesem, takiego jak Redis lub SQL Server, HybridCache
używa skonfigurowanej IDistributedCache
implementacji, jeśli istnieje. Ale nawet bez IDistributedCache
implementacji HybridCache
usługa nadal zapewnia buforowanie procesów i ochronę stampede.
Optymalizowanie wydajności
Aby zoptymalizować wydajność, skonfiguruj do HybridCache
ponownego użycia obiektów i unikaj byte[]
alokacji.
Ponowne używanie obiektów
W typowym istniejącym kodzie, który używa IDistributedCache
metody , każde pobieranie obiektu z pamięci podręcznej powoduje deserializacji. To zachowanie oznacza, że każdy współbieżny obiekt wywołujący otrzymuje oddzielne wystąpienie obiektu, które nie może wchodzić w interakcje z innymi wystąpieniami. Wynikiem jest bezpieczeństwo wątków, ponieważ nie ma ryzyka współbieżnych modyfikacji w tym samym wystąpieniu obiektu.
Ponieważ wiele użycia zostanie dostosowanych z istniejącego HybridCache
IDistributedCache
kodu, zachowuje to zachowanie domyślnie, HybridCache
aby uniknąć wprowadzania usterek współbieżności. Jednak obiekty są z natury bezpieczne wątkowo, jeśli:
- Są to niezmienne typy.
- Kod nie modyfikuje ich.
W takich przypadkach należy poinformować HybridCache
, że ponowne użycie wystąpień jest bezpieczne przez:
- Oznaczanie typu jako
sealed
. Słowosealed
kluczowe w języku C# oznacza, że nie można dziedziczyć klasy. - Stosowanie atrybutu
[ImmutableObject(true)]
do typu. Atrybut[ImmutableObject(true)]
wskazuje, że nie można zmienić stanu obiektu po jego utworzeniu.
Przez ponowne użycie wystąpień HybridCache
może zmniejszyć obciążenie związane z alokacją procesora CPU i obiektu skojarzonymi z deserializacji poszczególnych wywołań. Może to prowadzić do poprawy wydajności w scenariuszach, w których buforowane obiekty są duże lub często używane.
Unikaj byte[]
alokacji
HybridCache
Udostępnia również opcjonalne interfejsy API dla IDistributedCache
implementacji, aby uniknąć byte[]
alokacji. Ta funkcja jest implementowana przez wersje Microsoft.Extensions.Caching.StackExchangeRedis
zapoznawcza pakietów i Microsoft.Extensions.Caching.SqlServer
. Aby uzyskać więcej informacji, zobacz IBufferDistributedCache Oto polecenia interfejsu wiersza polecenia platformy .NET służące do instalowania pakietów:
dotnet add package Microsoft.Extensions.Caching.StackExchangeRedis --prerelease
dotnet add package Microsoft.Extensions.Caching.SqlServer --prerelease
Niestandardowe implementacje usługi HybridCache
Konkretna implementacja klasy abstrakcyjnej HybridCache
jest zawarta w strukturze udostępnionej i jest dostarczana za pośrednictwem wstrzykiwania zależności. Deweloperzy są jednak mile widziani, aby zapewnić niestandardowe implementacje interfejsu API.
Zgodność
Biblioteka obsługuje starsze środowiska uruchomieniowe platformy .NET w dół do programów .NET Framework 4.7.2 i .NET Standard 2.0.
Dodatkowe zasoby
Aby uzyskać więcej informacji na temat HybridCache
programu , zobacz następujące zasoby:
Opinia
https://aka.ms/ContentUserFeedback.
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź:Prześlij i wyświetl opinię dla