ASP.NET Core'da HybridCache kitaplığı

Makale
11/07/2024

Önemli

HybridCacheşu anda önizleme aşamasındadır, ancak .NET Uzantıları'nın gelecekteki küçük bir sürümünde .NET 9.0'ın ardından tamamen yayımlanacaktır.

Bu makalede, ASP.NET Core uygulamasında kitaplığın HybridCache nasıl yapılandırılıp kullanılacağı açıklanmaktadır. Kitaplığa giriş için Önbelleğe almaya genel bakış bölümüne bakın.HybridCache

Kitaplığı alma

Microsoft.Extensions.Caching.Hybrid paketini yükleyin.

dotnet add package Microsoft.Extensions.Caching.Hybrid --version "9.0.0-preview.7.24406.2"

Hizmeti kaydetme

HybridCache çağrısı AddHybridCacheyaparak hizmeti bağımlılık ekleme (DI) kapsayıcısına ekleyin:

// Add services to the container.
var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddAuthorization();

builder.Services.AddHybridCache();

Yukarıdaki kod, hizmeti varsayılan seçeneklerle kaydeder HybridCache . Kayıt API'si ayrıca seçenekleri ve serileştirmeyi de yapılandırabilir.

Önbellek girdilerini alma ve depolama

Hizmet HybridCache , bir anahtar alarak iki aşırı yükleme içeren bir GetOrCreateAsync yöntem sağlar ve:

Bir fabrika yöntemi.
Durum ve fabrika yöntemi.

yöntemi, nesneyi birincil önbellekten almayı denemek için anahtarını kullanır. Öğe birincil önbellekte bulunmazsa (önbellek hatası), yapılandırıldıysa ikincil önbelleği denetler. Verileri orada bulamazsa (başka bir önbellek kaçırması), nesneyi veri kaynağından almak için fabrika yöntemini çağırır. Ardından nesneyi hem birincil hem de ikincil önbelleklerde depolar. Nesne birincil veya ikincil önbellekte (önbellek isabeti) bulunursa fabrika yöntemi hiçbir zaman çağrılmaz.

Hizmet, HybridCache belirli bir anahtar için yalnızca bir eşzamanlı çağıranın fabrika yöntemini çağırmasını ve diğer tüm arayanların bu çağrının sonucunu beklemesini sağlar. geçirilen CancellationToken GetOrCreateAsync , tüm eş zamanlı arayanların birleştirilmiş iptalini temsil eder.

Ana `GetOrCreateAsync` aşırı yükleme

durum bilgisi olmayan aşırı yüklemesi GetOrCreateAsync çoğu senaryo için önerilir. Çağıracak kod nispeten basittir. Bir örnek aşağıda verilmiştir:

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),
            cancellationToken: token
        );
    }

    public async Task<string> GetDataFromTheSourceAsync(string name, int id, CancellationToken token)
    {
        string someInfo = $"someinfo-{name}-{id}";
        return someInfo;
    }
}

Alternatif `GetOrCreateAsync` aşırı yükleme

Alternatif aşırı yükleme, yakalanan değişkenlerden ve örnek başına geri çağırmalardan kaynaklanan bazı ek yükleri azaltabilir, ancak daha karmaşık bir koda neden olabilir. Çoğu senaryoda performans artışı kod karmaşıklığından daha ağır basmıyor. Alternatif aşırı yüklemeyi kullanan bir örnek aşağıda verilmişti:

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),
            cancellationToken: token
        );
    }

    public async Task<string> GetDataFromTheSourceAsync(string name, int id, CancellationToken token)
    {
        string someInfo = $"someinfo-{name}-{id}";
        return someInfo;
    }
}

`SetAsync` yöntemi

Birçok senaryoda, GetOrCreateAsync gereken tek API'dir. Ancak HybridCache , SetAsync önce almaya çalışmadan bir nesneyi önbellekte depolaması gerekir.

Anahtara göre önbellek girdilerini kaldırma

Önbellek girdisinin temel verileri süresi dolmadan önce değiştiğinde, girdinin anahtarıyla birlikte çağırarak RemoveAsync girdiyi açıkça kaldırın. Aşırı yükleme , anahtar değerlerin bir koleksiyonunu belirtmenize olanak tanır.

Bir girdi kaldırıldığında, hem birincil hem de ikincil önbelleklerden kaldırılır.

Etikete göre önbellek girdilerini kaldırma

Etiketler, önbellek girdilerini gruplandırmak ve bunları birlikte geçersiz kılmak için kullanılabilir.

çağrısı yaparken GetOrCreateAsyncetiketleri aşağıdaki örnekte gösterildiği gibi ayarlayın:

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,
            cancellationToken: token
        );
    }
    
    public async Task<string> GetDataFromTheSourceAsync(string name, int id, CancellationToken token)
    {
        string someInfo = $"someinfo-{name}-{id}";
        return someInfo;
    }
}

Etiket değeriyle çağırarak RemoveByTagAsync belirtilen etiketin tüm girdilerini kaldırın. Aşırı yükleme , etiket değerleri koleksiyonu belirtmenize olanak tanır.

Bir girdi kaldırıldığında, hem birincil hem de ikincil önbelleklerden kaldırılır.

Seçenekler

yöntemi genel AddHybridCache varsayılanları yapılandırmak için kullanılabilir. Aşağıdaki örnekte, kullanılabilir seçeneklerden bazılarının nasıl yapılandırılır gösterilmektedir:

// 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)
        };
    });

yöntemi, GetOrCreateAsync belirli bir HybridCacheEntryOptions önbellek girdisinin genel varsayılanlarını geçersiz kılmak için bir nesnesi de alabilir. Bir örnek aşağıda verilmiştir:

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,
            cancellationToken: token
        );
    }
    
    public async Task<string> GetDataFromTheSourceAsync(string name, int id, CancellationToken token)
    {
        string someInfo = $"someinfo-{name}-{id}";
        return someInfo;
    }
}

Seçenekler hakkında daha fazla bilgi için kaynak koduna bakın:

HybridCacheOptions sınıfı.
HybridCacheEntryOptions sınıfı.

Sınırlar

aşağıdaki özellikleri HybridCacheOptions , tüm önbellek girdilerine uygulanan sınırları yapılandırmanıza olanak sağlar:

MaximumPayloadBytes - Önbellek girdisinin en büyük boyutu. Varsayılan değer 1 MB'tır. Bu boyuttaki değerleri depolama girişimleri günlüğe kaydedilir ve değer önbellekte depolanmaz.
MaximumKeyLength - Önbellek anahtarının uzunluk üst sınırı. Varsayılan değer 1024 karakterdir. Bu boyuttaki değerleri depolama girişimleri günlüğe kaydedilir ve değer önbellekte depolanmaz.

Serileştirme

İkincil, işlem dışı önbelleğin kullanılması için serileştirme gerekir. Serileştirme, hizmeti kaydetmenin HybridCache bir parçası olarak yapılandırılır. Türe özgü ve genel amaçlı serileştiriciler çağrıdan AddHybridCache zincirlenmiş ve AddSerializerFactory yöntemleri aracılığıyla AddSerializer yapılandırılabilir. Varsayılan olarak, kitaplık dahili olarak işler string ve byte[] diğer her şey için kullanır System.Text.Json . HybridCache protobuf veya XML gibi diğer serileştiricileri de kullanabilir.

Aşağıdaki örnek, hizmeti türe özgü bir protobuf serileştiricisi kullanacak şekilde yapılandırır:

// Add services to the container.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthorization();

builder.Services.AddHybridCache(options =>
    {
        options.DefaultEntryOptions = new HybridCacheEntryOptions
        {
            Expiration = TimeSpan.FromSeconds(10),
            LocalCacheExpiration = TimeSpan.FromSeconds(5)
        };
    }).AddSerializer<SomeProtobufMessage, 
        GoogleProtobufSerializer<SomeProtobufMessage>>();

Aşağıdaki örnek, hizmeti birçok protobuf türünü işleyebilen genel amaçlı bir protobuf seri hale getirici kullanacak şekilde yapılandırır:

// Add services to the container.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthorization();

builder.Services.AddHybridCache(options =>
{
    options.DefaultEntryOptions = new HybridCacheEntryOptions
    {
        Expiration = TimeSpan.FromSeconds(10),
        LocalCacheExpiration = TimeSpan.FromSeconds(5)
    };
}).AddSerializerFactory<GoogleProtobufSerializerFactory>();

İkincil önbellek, Redis veya SqlServer gibi bir veri deposu gerektirir. Redis için Azure Cache kullanmak için, örneğin:

Microsoft.Extensions.Caching.StackExchangeRedis paketini yükleyin.
bir Redis için Azure Cache örneği oluşturun.
Redis örneğine bağlanan bir bağlantı dizesi alın. Azure portalındaki Genel Bakış sayfasında Erişim anahtarlarını göster'i seçerek bağlantı dizesi bulun.
bağlantı dizesi uygulamanın yapılandırmasında depolayın. Örneğin, bölümündeki bağlantı dizesi ConnectionStrings ile aşağıdaki JSON'a benzeyen bir kullanıcı gizli dizileri dosyası kullanın. değerini gerçek bağlantı dizesi ile değiştirin<the connection string>:
```
{
  "ConnectionStrings": {
    "RedisConnectionString": "<the connection string>"
  }
}
```
Redis paketinin IDistributedCache sağladığı uygulamayı DI'ye kaydedin. Bunu yapmak için öğesini arayın AddStackExchangeRedisCacheve bağlantı dizesi geçirin. Örneğin:
```
builder.Services.AddStackExchangeRedisCache(options =>
{
    options.Configuration = 
        builder.Configuration.GetConnectionString("RedisConnectionString");
});
```
Redis IDistributedCache uygulaması artık uygulamanın DI kapsayıcısından kullanılabilir. HybridCache bunu ikincil önbellek olarak kullanır ve bunun için yapılandırılan seri hale getiriciyi kullanır.

Daha fazla bilgi için bkz . HybridCache serileştirme örnek uygulaması.

Önbellek depolama

Varsayılan olarak HybridCache birincil önbellek depolama alanı için kullanır MemoryCache . Önbellek girdileri işlem içinde depolanır, bu nedenle her sunucu işlemi yeniden başlatıldığında kaybolan ayrı bir önbelleğe sahiptir. Redis veya SQL Server HybridCache gibi ikincil işlem dışı depolama için, varsa yapılandırılmış IDistributedCache uygulamayı kullanır. Ancak uygulama IDistributedCacheHybridCache olmasa bile hizmet yine de işlem içi önbelleğe alma ve damgalı koruma sağlar.

Performansı iyileştirme

Performansı iyileştirmek için nesneleri yeniden kullanacak ve ayırmalardan kaçınacak byte[] şekilde yapılandırınHybridCache.

Nesneleri yeniden kullanma

Örnekleri yeniden kullanarak, HybridCache çağrı başına seri durumdan çıkarma ile ilişkili CPU ve nesne ayırma yükünü azaltabilir. Bu, önbelleğe alınan nesnelerin büyük olduğu veya sık erişildiği senaryolarda performans geliştirmelerine yol açabilir.

kullanan IDistributedCachetipik mevcut kodda, önbellekten bir nesnenin her alınması seri durumdan çıkarılır. Bu davranış, her eş zamanlı çağıranın nesnenin ayrı bir örneğini aldığı ve diğer örneklerle etkileşim kuramaz olduğu anlamına gelir. Sonuç olarak iş parçacığı güvenliği elde edilir çünkü aynı nesne örneğinde eşzamanlı değişiklik yapılması riski yoktur.

Mevcut IDistributedCache koddan çok fazla HybridCache kullanım uyarlanacağından, HybridCache eşzamanlılık hatalarının oluşmasını önlemek için bu davranışı varsayılan olarak korur. Ancak, aşağıdaki durumlarda nesneler doğal olarak iş parçacığı açısından güvenlidir:

Bunlar sabit türlerdir.
Kod bunları değiştirmez.

Bu gibi durumlarda örneklerin yeniden kullanılmasının güvenli olduğunu şu şekilde bildirin HybridCache :

Türü olarak sealedişaretleme. sealed C# dilindeki anahtar sözcük, sınıfın devralınamaz olduğu anlamına gelir.
özniteliği türüne [ImmutableObject(true)] uygulanıyor. [ImmutableObject(true)] özniteliği, nesne oluşturulduktan sonra nesnenin durumunun değiştirilebileceğini gösterir.

Ayırmalardan kaçının `byte[]`

HybridCacheayrıca, ayırmaları önlemek byte[] için uygulamalar için IDistributedCache isteğe bağlı API'ler sağlar. Bu özellik ve Microsoft.Extensions.Caching.SqlServer paketlerinin önizleme sürümleri Microsoft.Extensions.Caching.StackExchangeRedis tarafından uygulanır. Daha fazla bilgi için bkz . IBufferDistributedCache Paketleri yüklemek için .NET CLI komutları:

dotnet add package Microsoft.Extensions.Caching.StackExchangeRedis --prerelease

dotnet add package Microsoft.Extensions.Caching.SqlServer --prerelease

Özel HybridCache uygulamaları

Soyut sınıfın HybridCache somut bir uygulaması paylaşılan çerçeveye dahil edilir ve bağımlılık ekleme yoluyla sağlanır. Ancak geliştiriciler API'nin özel uygulamalarını sağlayabilir.

Uyumluluk

Kitaplık HybridCache , .NET Framework 4.7.2 ve .NET Standard 2.0'a kadar eski .NET çalışma zamanlarını destekler.

Ek kaynaklar

hakkında HybridCachedaha fazla bilgi için aşağıdaki kaynaklara bakın:

GitHub sorunu dotnet/aspnetcore #54647.
HybridCache kaynak kodu

Aracılığıyla paylaş

ASP.NET Core'da HybridCache kitaplığı

Kitaplığı alma

Hizmeti kaydetme

Önbellek girdilerini alma ve depolama

Ana GetOrCreateAsync aşırı yükleme

Alternatif GetOrCreateAsync aşırı yükleme

SetAsync yöntemi

Anahtara göre önbellek girdilerini kaldırma

Etikete göre önbellek girdilerini kaldırma

Seçenekler

Sınırlar

Serileştirme

Önbellek depolama

Performansı iyileştirme

Nesneleri yeniden kullanma

Ayırmalardan kaçının byte[]

Özel HybridCache uygulamaları

Uyumluluk

Ek kaynaklar

Ek kaynaklar

Ana `GetOrCreateAsync` aşırı yükleme

Alternatif `GetOrCreateAsync` aşırı yükleme

`SetAsync` yöntemi

Ayırmalardan kaçının `byte[]`