diff --git a/15/umbraco-cms/.gitbook.yaml b/15/umbraco-cms/.gitbook.yaml index 094bb545459..9ba9b5b9bc6 100644 --- a/15/umbraco-cms/.gitbook.yaml +++ b/15/umbraco-cms/.gitbook.yaml @@ -104,3 +104,4 @@ redirects: extending/backoffice-tours: extending/README.md tutorials/creating-a-backoffice-tour: tutorials/overview.md extending/packages/types-of-packages: extending/packages/README.md + reference/configuration/nucachesettings: reference/configuration/cache-settings.md diff --git a/15/umbraco-cms/SUMMARY.md b/15/umbraco-cms/SUMMARY.md index b9ab37701c1..2dac08d1f64 100644 --- a/15/umbraco-cms/SUMMARY.md +++ b/15/umbraco-cms/SUMMARY.md @@ -47,6 +47,7 @@ * [Health Check Guides](extending/health-check/guides/README.md) * [Content Content Security Policy (CSP)](extending/health-check/guides/contentsecuritypolicy.md) * [Creating a Custom Database Table](extending/database.md) +* [Creating a Custom Seed Key Provider](extending/creating-custom-seed-key-provider.md) ## Reference @@ -70,7 +71,7 @@ * [Logging settings](reference/configuration/loggingsettings.md) * [Maximum Upload Size Settings](reference/configuration/maximumuploadsizesettings.md) * [Models builder settings](reference/configuration/modelsbuildersettings.md) - * [NuCache Settings](reference/configuration/nucachesettings.md) + * [Cache Settings](reference/configuration/cache-settings.md) * [Package Migration](reference/configuration/packagemigrationsettings.md) * [Plugins settings](reference/configuration/pluginssettings.md) * [Request handler settings](reference/configuration/requesthandlersettings.md) @@ -92,6 +93,7 @@ * [Using Umbraco services](reference/management/using-services/README.md) * [Content Type Service](reference/management/using-services/contenttypeservice.md) * [Cache & Distributed Cache](reference/cache/README.md) + * [Cache Seeding](reference/cache/cache-seeding.md) * [Examples](reference/cache/examples/README.md) * [Working with caching](reference/cache/examples/tags.md) diff --git a/15/umbraco-cms/extending/creating-custom-seed-key-provider.md b/15/umbraco-cms/extending/creating-custom-seed-key-provider.md new file mode 100644 index 00000000000..64fbd4ea869 --- /dev/null +++ b/15/umbraco-cms/extending/creating-custom-seed-key-provider.md @@ -0,0 +1,115 @@ +--- +description: A guide to creating a custom seed key provider for Umbraco +--- + +# Creating a Custom Seed Key Provider + +Umbraco uses a lazy loaded cache, which means that content is loaded into the cache on an as-needed basis. However, you may need specific content to always be in the cache. To achieve this you can implement your own custom seed key providers. + +There are two types of seed key providers: `IDocumentSeedKeyProvider` for documents and `IMediaSeedKeyProvider` for media. As these interfaces are identical only `IDocumentSeedKeyProvider` is demonstrated in this article. + +{% hint style="warning" %} +Seed keys are cached and calculated once. Any documents created after the site has started will not be included in the seed keys until after a server restart. +{% endhint %} + +## Implementation + +This example implements a `IDocumentSeedKeyProvider` which seeds all the children of a node, in this case blog posts. + +1. Create a new class called `BlogSeedKeyProvider` that implements `IDocumentSeedKeyProvider`. + +```csharp +using Umbraco.Cms.Infrastructure.HybridCache; + +namespace MySite.SeedKeyProviders; + +public class BlogSeedKeyProvider : IDocumentSeedKeyProvider +{ + public ISet GetSeedKeys() + { + } +} +``` + +Next we'll inject the `IDocumentNavigationQueryService` in order to get the children of the blog node. + +```csharp +using Umbraco.Cms.Core.Services.Navigation; +using Umbraco.Cms.Infrastructure.HybridCache; + +namespace MySite.SeedKeyProviders; + +public class BlogSeedKeyProvider : IDocumentSeedKeyProvider +{ + private readonly IDocumentNavigationQueryService _documentNavigationQueryService; + + public BlogSeedKeyProvider(IDocumentNavigationQueryService documentNavigationQueryService) + => _documentNavigationQueryService = documentNavigationQueryService; + +{...} +``` + +3. Parse a hardcoded string to a GUID. +4. Use the `IDocumentNavigationQueryService` to get the children of the blog node. +5. Return their keys as a `HashSet`. + +```csharp +public ISet GetSeedKeys() +{ + var blogRoot = Guid.Parse("a5fdb22d-b7f2-4a59-8c4e-46ed86bde56c"); + + if (_documentNavigationQueryService.TryGetChildrenKeys(blogRoot, out IEnumerable blogPostKeys)) + { + return new HashSet(blogPostKeys); + } + + return new HashSet(); +} +``` +Since this returns it as a set, and all the sets get unioned, we do not have to worry about duplicates. + +The final class looks like this: + +```csharp +using Umbraco.Cms.Core.Services.Navigation; +using Umbraco.Cms.Infrastructure.HybridCache; + +namespace MySite.SeedKeyProviders; + +public class BlogSeedKeyProvider : IDocumentSeedKeyProvider +{ + private readonly IDocumentNavigationQueryService _documentNavigationQueryService; + + public BlogSeedKeyProvider(IDocumentNavigationQueryService documentNavigationQueryService) + => _documentNavigationQueryService = documentNavigationQueryService; + + public ISet GetSeedKeys() + { + var blogRoot = Guid.Parse("a5fdb22d-b7f2-4a59-8c4e-46ed86bde56c"); + + if (_documentNavigationQueryService.TryGetChildrenKeys(blogRoot, out IEnumerable blogPostKeys)) + { + return new HashSet(blogPostKeys); + } + + return new HashSet(); + } +} +``` + +### Registering the Seed Key Provider + +Now that the `BlogSeedKeyProvider` is implemented, it must be registered in the `Startup` class. + +```csharp +using MySite.SeedKeyProviders; +using Umbraco.Cms.Infrastructure.DependencyInjection; +using Umbraco.Cms.Infrastructure.HybridCache; + +WebApplicationBuilder builder = WebApplication.CreateBuilder(args); + +builder.Services.AddSingleton(); +{...} +``` + +All blogpost will now be seeded into the cache on startup, and will always be present in the cache. diff --git a/15/umbraco-cms/reference/cache/cache-seeding.md b/15/umbraco-cms/reference/cache/cache-seeding.md new file mode 100644 index 00000000000..c09cd4b5319 --- /dev/null +++ b/15/umbraco-cms/reference/cache/cache-seeding.md @@ -0,0 +1,42 @@ +--- +description: Information about cache seeding +--- + +# Cache Seeding + +Umbraco uses a lazy loaded cache, meaning content is loaded into the cache on an as-needed basis. Whenever a piece of content is shown on the website for the first time it first needs to be loaded into the cache. + +Loading the content into the cache causes a delay. This delay is dependent on the latency between your server and your database, but is generally minimal. +For certain pages, like the front page, you may not want this delay to be there. The role of cache seeding is meant to solve this issue. + +## How it works + +Cache seeding is based on the concept of an `ISeedKeyProvider`. The role of the seed key provider is to specify what keys need to be seeded. + +There are two types of seed key providers: an `IDocumentSeedKeyProvider` specifying which document should be seeded, and an `IMediaSeedKeyProvider` specifying which media should be seeded. + +During startup, all the `ISeedKeyProviders` are run, and the keys they return are seeded into their respective caches, `IPublishedContentCache` for documents, and `IPublishedMediaCache` for media. Additionally, whenever a document or media is changed, the cache will immediately be updated with the changed content. This ensures that the content is always present in the cache. + +Whenever a piece of content is changed, the seeded keys must be checked, to see if the updated content was seeded. Because of the need the check all seeded keys, Umbraco caches the keys themselves during startup. This means that if you have a dynamic seed key provider, any newly added content will not be considered seeded until the server restarts. For instance, when seeding by Document Type any new content using the specified Document Type will not be seeded until the server is restarted. + +## Seed key providers + +### Default implementations + +By default, Umbraco ships with two seed key providers for documents, and one for media. + +For documents, the `ContentTypeSeedKeyProvider` seeds all documents of the given Document Types specified in the `appSettings.json` file. + +For documents and media, the `BreadthFirstKeyProvider` does a breadth-first traversal of the content and media tree respectively. This will seed N number of content specified in the `appSettings.json` file. + +The default seed key provider configuration can be found in the [cache settings section.](../configuration/cache-settings.md). + +### Custom seed key providers + +It is also possible to implement custom seed key providers. These are run alongside the default seed key providers on startup. + +The returned keys of all the seed key providers are unioned into a single set. This means there will be no duplicates. + +As mentioned above the provided keys are cached. Only the keys returned at startup will be considered seeded until the server restarts and the provider is rerun. + +For a specific example of implementing a custom seed key provider, see [Creating a Custom Seed Key Provider](../extending/creating-custom-seed-key-provider.md). diff --git a/15/umbraco-cms/reference/configuration/cache-settings.md b/15/umbraco-cms/reference/configuration/cache-settings.md new file mode 100644 index 00000000000..ff396b51374 --- /dev/null +++ b/15/umbraco-cms/reference/configuration/cache-settings.md @@ -0,0 +1,184 @@ +--- +description: Information on the Cache settings section +--- + +# Cache Settings + +{% hint style="info" %} +Are you looking for the **NuCache Settings**? + +While most cache configurations are under the `Umbraco:CMS:Cache` settings node, a few remain under `Umbraco:CMS:NuCache`. [Learn more about this at the bottom of this article](#nucache-settings). +{% endhint %} + +## HybridCacheOptions + +Umbraco's cache is implemented using Microsofts `HybridCache`, which also has its own settings. For more information [see the HybridCache documentation](https://learn.microsoft.com/en-us/aspnet/core/performance/caching/hybrid?view=aspnetcore-9.0#options). + +### MaximumPayLoadBytes + +One `HybridCache` setting of particular interest is the `MaximumPayloadBytes` setting. This setting specifies the maximum size of a cache entry in bytes and replaces the `BTreeBlockSize` setting from NuCache. +The default from Microsoft is 1MB. However, this limit could quickly be reached, especially when using multiple languages or property editors like the block grid. +To avoid this Umbraco overrides the setting to 100MB by default. You can also configure this manually using a composer: + +```csharp +using Microsoft.Extensions.Caching.Hybrid; +using Umbraco.Cms.Core.Composing; + +namespace MySite.Caching; + +public class ConfigureCacheComposer : IComposer +{ + public void Compose(IUmbracoBuilder builder) + { + builder.Services.AddOptions().Configure(x => + { + x.MaximumPayloadBytes = 1024 * 1024 * 10; // 10MB + }); + } +} +``` + +## Seeding settings + +The Seeding settings allow you to specify which content should be seeded into your cache. For more information on cache seeding see the [Cache Seeding.](../cache/cache-seeding.md) article. + +### ContentTypeKeys + +The `ContentTypeKeys` setting specifies which Document Types should be seeded into the cache. The setting is a comma-separated list of Document Type keys. + +```json +"Umbraco": { + "CMS": { + "Cache": { + "ContentTypeKeys": ["e811405e-0190-4d3e-8387-7558521eec81", "419e89fb-8cff-4549-a074-9f8a30687828", "e0d71146-8205-4cf4-8236-f982b392259f"], + } + } +} +``` + +### DocumentBreadthFirstSeedCount + +The `DocumentBreadthFirstSeedCount` setting specifies how many documents should be seeded into the cache when doing a breadth-first traversal. The default value is 100. + +```json +"Umbraco": { + "CMS": { + "Cache": { + "DocumentBreadthFirstSeedCount": 500 + } + } +} +``` + +## MediaBreadthFirstSeedCount + +The `MediaBreadthFirstSeedCount` setting specifies how many media items should be seeded into the cache when doing a breadth-first traversal. The default value is 100. + +```json +"Umbraco": { + "CMS": { + "Cache": { + "MediaBreadthFirstSeedCount": 500 + } + } +} +``` + +## Cache Entry settings + +The Entry settings allow you to specify how long cache entries should be kept. The cache entry settings are identical for documents and media. + +## LocalCacheDuration + +Specifies the duration for which cache entries should be kept in the local memory cache. The default value is 24 hours. + +```json +"Umbraco": { + "CMS": { + "Cache": { + "Entry": { + "Document": { + "LocalCacheDuration": "2.00:00:00" + }, + "Media": { + "LocalCacheDuration": "50.00:00:00" + } + } + } + } +} +``` + +## RemoteCacheDuration + +Specifies the duration that cache entries should be kept in the remote cache, second level cache. This setting is only relevant if a second-level cache is configured. The default value is 1 year. + +```json +"Umbraco": { + "CMS": { + "Cache": { + "Entry": { + "Document": { + "RemoteCacheDuration": "100.00:00:00" + }, + "Media": { + "RemoteCacheDuration": "150.00:00:00" + } + } + } + } +} +``` + +## SeedCacheDuration + +Specifies the duration for which seeded cache entries should be kept in the cache. The default value is 1 year. + +```json +"Umbraco": { + "CMS": { + "Cache": { + "Entry": { + "Document": { + "SeedCacheDuration": "200.00:00:00" + }, + "Media": { + "SeedCacheDuration": "250.00:00:00" + } + } + } + } +} +``` + +# NuCache Settings + +For backward compatibility reasons, certain settings are under the `Umbraco:CMS:NuCache` settings node. + +## UsePagedSqlQuery + +Setting `UsePagedSqlQuery` to `False` your project will use the `Fetch` method instead of the `QueryPaged` method when rebuilding the NuCache files. This will increase performance on bigger Umbraco websites with a lot of content when rebuilding the NuCache. + +```json +"Umbraco": { + "CMS": { + "NuCache": { + "UsePagedSqlQuery": false + } + } + } + +``` +## SqlPageSize + +Specifying the `SqlPageSize` will change the size of the paged SQL queries. The default value is 1000. + +```json +"Umbraco": { + "CMS": { + "NuCache": { + "SqlPageSize": 500 + } + } + } +``` diff --git a/15/umbraco-cms/reference/configuration/nucachesettings.md b/15/umbraco-cms/reference/configuration/nucachesettings.md deleted file mode 100644 index 378a1be0596..00000000000 --- a/15/umbraco-cms/reference/configuration/nucachesettings.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -description: Information on the NuCache settings section ---- - -# NuCache Settings - -This settings section allows you to specify the block size of the BTree used by NuCache. This is configured by default, so you don't need to configure this. However it is possible with something like: - -```json -"Umbraco": { - "CMS": { - "NuCache": { - "BTreeBlockSize": 4096 - } - } -} -``` - -This is how NuCache is configured by default. It is important to mention that the block size must be a power of two, at least 512, and at most 65536 (64K). - -## UsePagedSqlQuery - -Setting `UsePagedSqlQuery` to `False` your project will use the `Fetch` method instead of the `QueryPaged` method when rebuilding the NuCache files. This will increase performance on bigger Umbraco websites with a lot of content when rebuilding the NuCache. - -```json -"Umbraco": { - "CMS": { - "NuCache": { - "UsePagedSqlQuery": false - } - } - } - -``` - -## Additional Settings - -It is possible to configure NuCache to work in memory only without reading/writing the NuCache database files. - -Startup duration may increase for larger sites during a "warm boot" but smaller sites should see minimal impact. - -The settings have not yet been exposed via the new configuration setup, instead you must configure with a composer. - -```csharp -public class DisableNuCacheDatabaseComposer : IComposer -{ - public void Compose(IUmbracoBuilder builder) - { - var settings = new Umbraco.Cms.Infrastructure.PublishedCache.PublishedSnapshotServiceOptions - { - IgnoreLocalDb = true - }; - builder.Services.AddSingleton(settings); - } -} -``` diff --git a/15/umbraco-cms/release-candidate-guide.md b/15/umbraco-cms/release-candidate-guide.md index a6b6fb6b078..37cf1cdfc6e 100644 --- a/15/umbraco-cms/release-candidate-guide.md +++ b/15/umbraco-cms/release-candidate-guide.md @@ -64,6 +64,9 @@ Here is a list of all the articles that are new to this version or have been upd * [Tutorial: Extending the Help Menu](tutorials/extending-the-help-menu.md) * [Running Umbraco in Docker using Docker Compose](fundamentals/setup/install/running-umbraco-on-docker-locally.md) +* [Creating a Custom Seed Key Provider](extending/creating-custom-seed-key-provider.md) +* [Cache Settings](reference/configuration/cache-settings.md) +* [Cache Seeding](reference/cache/cache-seeding.md) ### Updated articles