From 40ff469a641dfef87eafc549541f85d02eb112e9 Mon Sep 17 00:00:00 2001 From: nikolajlauridsen Date: Mon, 21 Oct 2024 15:01:59 +0200 Subject: [PATCH 01/17] Add custom seed provider documentation --- .../creating-custom-seed-key-provider.md | 116 ++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 15/umbraco-cms/extending/creating-custom-seed-key-provider.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..6380a86c1ed --- /dev/null +++ b/15/umbraco-cms/extending/creating-custom-seed-key-provider.md @@ -0,0 +1,116 @@ +--- +description: A guid to creating a custom seed key provider for Umbraco +--- + +# Creating a Custom Seed Key Provider + +From version 15 and onwards Umbraco uses a lazy loaded cache, this means content is loaded into the cache on an as-needed basis. +However, you may some specific content to always be in the cache, to achieve this you can implement your own custom seed key providers. + +There is two types of seed key providers: `IDocumentSeedKeyProvider` for documents and `IMediaSeedKeyProvider` for media, +these interfaces are identical so only `IDocumentSeedKeyProvider` is demonstrated here. + +{% hint style="warning" %} +Seed keys are themselves cached and only calculated once, this means that any documents created after the site has started won't be included in the seed keys untill ther server has restarted. +{% endhint %} + +## Implementation + +This example implements a `IDocumentSeedKeyProvider` which seeds all the children of a node, in this case blog posts. + +First we'll create a 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; + +{...} +``` + +Now we can parse a hardcoded string to a guid and use the `IDocumentNavigationQueryService` to get the children of the blog node and 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(); +} +``` +We since we're returning it as a set, and all the sets gets unioned, we don't 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 we have implemented the `BlogSeedKeyProvider` we need to register it in the `Startup` class. + +```csharp +using MySite.SeedKeyProviders; +using Umbraco.Cms.Infrastructure.DependencyInjection; +using Umbraco.Cms.Infrastructure.HybridCache; +using Umbraco.Cms.Web.UI; + +WebApplicationBuilder builder = WebApplication.CreateBuilder(args); + +builder.Services.AddSingleton(); +{...} +``` + +Now all our blogpost will be seeded into the cache on startup, and will always be present in the cache. From 0d8d3ce6f12dffcd025735bb034d5a5a23b31217 Mon Sep 17 00:00:00 2001 From: nikolajlauridsen Date: Mon, 21 Oct 2024 15:22:48 +0200 Subject: [PATCH 02/17] Remove unnecessary using --- 15/umbraco-cms/extending/creating-custom-seed-key-provider.md | 1 - 1 file changed, 1 deletion(-) diff --git a/15/umbraco-cms/extending/creating-custom-seed-key-provider.md b/15/umbraco-cms/extending/creating-custom-seed-key-provider.md index 6380a86c1ed..62a2be0a41f 100644 --- a/15/umbraco-cms/extending/creating-custom-seed-key-provider.md +++ b/15/umbraco-cms/extending/creating-custom-seed-key-provider.md @@ -105,7 +105,6 @@ Now that we have implemented the `BlogSeedKeyProvider` we need to register it in using MySite.SeedKeyProviders; using Umbraco.Cms.Infrastructure.DependencyInjection; using Umbraco.Cms.Infrastructure.HybridCache; -using Umbraco.Cms.Web.UI; WebApplicationBuilder builder = WebApplication.CreateBuilder(args); From ec8b569bac62a61c2dd617461bd01b2424829dc8 Mon Sep 17 00:00:00 2001 From: nikolajlauridsen Date: Tue, 22 Oct 2024 11:06:39 +0200 Subject: [PATCH 03/17] Add general cache seeding and configuration information --- .../creating-custom-seed-key-provider.md | 2 +- .../reference/cache/cache-seeding.md | 42 +++++ .../reference/configuration/cache-settings.md | 151 ++++++++++++++++++ .../configuration/nucachesettings.md | 56 ------- 4 files changed, 194 insertions(+), 57 deletions(-) create mode 100644 15/umbraco-cms/reference/cache/cache-seeding.md create mode 100644 15/umbraco-cms/reference/configuration/cache-settings.md delete mode 100644 15/umbraco-cms/reference/configuration/nucachesettings.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 index 62a2be0a41f..bc9c6b17375 100644 --- a/15/umbraco-cms/extending/creating-custom-seed-key-provider.md +++ b/15/umbraco-cms/extending/creating-custom-seed-key-provider.md @@ -1,5 +1,5 @@ --- -description: A guid to creating a custom seed key provider for Umbraco +description: A guide to creating a custom seed key provider for Umbraco --- # Creating a Custom Seed Key Provider 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..2cfba3881f1 --- /dev/null +++ b/15/umbraco-cms/reference/cache/cache-seeding.md @@ -0,0 +1,42 @@ +--- +description: Information about cache seeding +--- + +# Cache Seeding + +From version 15 and onwards Umbraco uses a lazy loaded cache, this means content is loaded into the cache on an as-needed basis +I.E. 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. +However, for certain pages, for instance the front page, you may not want this delay to be there, the role of cache seeding is to solve this issue. + +## How it works + +Cache seeding is based upon the concept of a `ISeedKeyProvider`, the role of the seed key provider, is to specify what keys needs to be seeded. +There's two types of seed key providers, a `IDocumentSeedKeyProvider` which specifies which document should be seeded, and a `IMediaSeedKeyProvider` which specifies 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 then later changed, the cache will be updated with the changed content immediately, ensuring the content is always present in the case. +However, here it's important to note, that this means that whenever a piece of content is changed, Umbraco needs to go through the seeded keys to see if it's a piece of seeded content that was updated. +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 won't be considered seeded until the server restarts, +for instance when seeding by document type any new content using the specified document type won't be seeded until a server restart. + +## Seed key providers + +### Default implementations. + +By default, umbraco ships with two seed key providers for documents, and a single one for media. + +For documents there is the `ContentTypeSeedKeyProvider` this seeds all documents of the given document types specified through app settings. + +For both documents and media there is the `BreadthFirstKeyProvider` this provider does a breadth first traversal of the content and media tree respectively, seeding N number of content specified in the app settings. + +Configuration for the default seed key providers can be found in the [cache settings section.](../configuration/cache-settings.md) + +### Custom seed key providers + +It's also possible to implement your own seed key providers, these are run alongside the default seed key providers on startup. +The returned keys are of all the seed key providers are unioned into a single set, this means that there will be no duplicates, so you don't need to worry consider this. +However, as mentioned above the provided keys are cached, meaning that only the keys returned at startup will be considered seeded until the server restarts and the provider is run again. + +For a specific example of how to implement 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..2da39c8ebce --- /dev/null +++ b/15/umbraco-cms/reference/configuration/cache-settings.md @@ -0,0 +1,151 @@ +--- +description: Information on the Cache settings section +--- + +# Cache settings + +## Seeding settings + +The seeding settings allows you to specify which content should be seeded into your cache, for more information on cache seeding see [Cache Seeding.](../cache/cache-seeding.md) + +### ContentTypeKeys + +The `ContentTypeKeys` setting is used to specify 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 is used to specify 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 is used to specify 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 allows you to specify how long cache entries should be kept in the cache, the cache entry settings are identical for documents and media. + +## LocalCacheDuration + +Specifies the duration that 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 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 that 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 backwards compatibility reasons, certain settings are still located 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, by default the 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); - } -} -``` From fdc7bfa4f974ee03ff02dcc5f5cd3813251c5c28 Mon Sep 17 00:00:00 2001 From: nikolajlauridsen Date: Tue, 22 Oct 2024 12:53:31 +0200 Subject: [PATCH 04/17] Minor fixes --- 15/umbraco-cms/reference/cache/cache-seeding.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/15/umbraco-cms/reference/cache/cache-seeding.md b/15/umbraco-cms/reference/cache/cache-seeding.md index 2cfba3881f1..3366a095716 100644 --- a/15/umbraco-cms/reference/cache/cache-seeding.md +++ b/15/umbraco-cms/reference/cache/cache-seeding.md @@ -5,7 +5,7 @@ description: Information about cache seeding # Cache Seeding From version 15 and onwards Umbraco uses a lazy loaded cache, this means content is loaded into the cache on an as-needed basis -I.E. whenever a piece of content is shown on the website for the first time it first needs to be loaded into the cache. +that is 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. However, for certain pages, for instance the front page, you may not want this delay to be there, the role of cache seeding is to solve this issue. @@ -16,10 +16,10 @@ Cache seeding is based upon the concept of a `ISeedKeyProvider`, the role of the There's two types of seed key providers, a `IDocumentSeedKeyProvider` which specifies which document should be seeded, and a `IMediaSeedKeyProvider` which specifies 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 then later changed, the cache will be updated with the changed content immediately, ensuring the content is always present in the case. +Additionally, whenever a document or media is then later changed, the cache will be updated with the changed content immediately, ensuring the content is always present in the cache. However, here it's important to note, that this means that whenever a piece of content is changed, Umbraco needs to go through the seeded keys to see if it's a piece of seeded content that was updated. 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 won't be considered seeded until the server restarts, -for instance when seeding by document type any new content using the specified document type won't be seeded until a server restart. +for instance when seeding by Document Type any new content using the specified Document Type won't be seeded until a server restart. ## Seed key providers @@ -27,7 +27,7 @@ for instance when seeding by document type any new content using the specified d By default, umbraco ships with two seed key providers for documents, and a single one for media. -For documents there is the `ContentTypeSeedKeyProvider` this seeds all documents of the given document types specified through app settings. +For documents there is the `ContentTypeSeedKeyProvider` this seeds all documents of the given Document Types specified through app settings. For both documents and media there is the `BreadthFirstKeyProvider` this provider does a breadth first traversal of the content and media tree respectively, seeding N number of content specified in the app settings. From da9ae706e67c0061205362772de5d19e7c1a37ba Mon Sep 17 00:00:00 2001 From: nikolajlauridsen Date: Tue, 22 Oct 2024 13:05:01 +0200 Subject: [PATCH 05/17] Few more fixes --- 15/umbraco-cms/reference/cache/cache-seeding.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/15/umbraco-cms/reference/cache/cache-seeding.md b/15/umbraco-cms/reference/cache/cache-seeding.md index 3366a095716..164f73dbd38 100644 --- a/15/umbraco-cms/reference/cache/cache-seeding.md +++ b/15/umbraco-cms/reference/cache/cache-seeding.md @@ -23,9 +23,9 @@ for instance when seeding by Document Type any new content using the specified D ## Seed key providers -### Default implementations. +### Default implementations -By default, umbraco ships with two seed key providers for documents, and a single one for media. +By default, Umbraco ships with two seed key providers for documents, and a single one for media. For documents there is the `ContentTypeSeedKeyProvider` this seeds all documents of the given Document Types specified through app settings. From d7698412340b2e594d37669f7678823bcffab7a0 Mon Sep 17 00:00:00 2001 From: sofietoft Date: Thu, 24 Oct 2024 09:34:44 +0200 Subject: [PATCH 06/17] Fixed long sentences --- .../reference/cache/cache-seeding.md | 31 ++++++++++--------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/15/umbraco-cms/reference/cache/cache-seeding.md b/15/umbraco-cms/reference/cache/cache-seeding.md index 164f73dbd38..d6b177f0a6a 100644 --- a/15/umbraco-cms/reference/cache/cache-seeding.md +++ b/15/umbraco-cms/reference/cache/cache-seeding.md @@ -12,31 +12,32 @@ However, for certain pages, for instance the front page, you may not want this d ## How it works -Cache seeding is based upon the concept of a `ISeedKeyProvider`, the role of the seed key provider, is to specify what keys needs to be seeded. -There's two types of seed key providers, a `IDocumentSeedKeyProvider` which specifies which document should be seeded, and a `IMediaSeedKeyProvider` which specifies which media should be seeded. +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. -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 then later changed, the cache will be updated with the changed content immediately, ensuring the content is always present in the cache. -However, here it's important to note, that this means that whenever a piece of content is changed, Umbraco needs to go through the seeded keys to see if it's a piece of seeded content that was updated. -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 won't be considered seeded until the server restarts, -for instance when seeding by Document Type any new content using the specified Document Type won't be seeded until a server restart. +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 a single one for media. +By default, Umbraco ships with two seed key providers for documents, and one for media. -For documents there is the `ContentTypeSeedKeyProvider` this seeds all documents of the given Document Types specified through app settings. +For documents, the `ContentTypeSeedKeyProvider` seeds all documents of the given Document Types specified in the `appSettings.json` file. -For both documents and media there is the `BreadthFirstKeyProvider` this provider does a breadth first traversal of the content and media tree respectively, seeding N number of content specified in the app settings. +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. -Configuration for the default seed key providers can be found in the [cache settings section.](../configuration/cache-settings.md) +The default seed key provider configuration can be found in the [cache settings section.](../configuration/cache-settings.md). ### Custom seed key providers -It's also possible to implement your own seed key providers, these are run alongside the default seed key providers on startup. -The returned keys are of all the seed key providers are unioned into a single set, this means that there will be no duplicates, so you don't need to worry consider this. -However, as mentioned above the provided keys are cached, meaning that only the keys returned at startup will be considered seeded until the server restarts and the provider is run again. +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 how to implement a custom seed key provider, see [Creating a Custom Seed Key Provider](../extending/creating-custom-seed-key-provider.md). +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). From ab35a91cc8886e16c013536ec98d5c9e5bdc78d0 Mon Sep 17 00:00:00 2001 From: sofietoft Date: Thu, 24 Oct 2024 09:40:44 +0200 Subject: [PATCH 07/17] Fixed long sentences --- .../reference/configuration/cache-settings.md | 25 +++++++++---------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/15/umbraco-cms/reference/configuration/cache-settings.md b/15/umbraco-cms/reference/configuration/cache-settings.md index 2da39c8ebce..86e1bfbb581 100644 --- a/15/umbraco-cms/reference/configuration/cache-settings.md +++ b/15/umbraco-cms/reference/configuration/cache-settings.md @@ -6,11 +6,11 @@ description: Information on the Cache settings section ## Seeding settings -The seeding settings allows you to specify which content should be seeded into your cache, for more information on cache seeding see [Cache Seeding.](../cache/cache-seeding.md) +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 is used to specify which document types should be seeded into the cache. The setting is a comma-separated list of document type keys. +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": { @@ -24,8 +24,7 @@ The `ContentTypeKeys` setting is used to specify which document types should be ### DocumentBreadthFirstSeedCount -The `DocumentBreadthFirstSeedCount` setting is used to specify how many documents should be seeded into the cache when doing a breadth first traversal, the default value is 100. - +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": { @@ -39,7 +38,7 @@ The `DocumentBreadthFirstSeedCount` setting is used to specify how many document ## MediaBreadthFirstSeedCount -The `MediaBreadthFirstSeedCount` setting is used to specify how many media items should be seeded into the cache when doing a breadth first traversal, the default value is 100. +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": { @@ -51,13 +50,13 @@ The `MediaBreadthFirstSeedCount` setting is used to specify how many media items } ``` -## Cache entry settings +## Cache Entry settings -The entry settings allows you to specify how long cache entries should be kept in the cache, the cache entry settings are identical for documents and media. +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 that cache entries should be kept in the local memory cache, the default value is 24 hours. +Specifies the duration that cache entries should be kept in the local memory cache. The default value is 24 hours. ```json "Umbraco": { @@ -78,7 +77,7 @@ Specifies the duration that cache entries should be kept in the local memory cac ## RemoteCacheDuration -Specifies the duration that cache entries should be kept in the remote cache, second level cache, this setting is only relevant if second level cache is configured. The default value is 1 year. +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": { @@ -99,7 +98,7 @@ Specifies the duration that cache entries should be kept in the remote cache, se ## SeedCacheDuration -Specifies the duration that seeded cache entries should be kept in the cache. The default value is 1 year. +Specifies the duration for which seeded cache entries should be kept in the cache. The default value is 1 year. ```json "Umbraco": { @@ -120,11 +119,11 @@ Specifies the duration that seeded cache entries should be kept in the cache. Th # NuCache Settings -For backwards compatibility reasons, certain settings are still located under the `Umbraco:CMS:NuCache` settings node. +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. +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": { @@ -138,7 +137,7 @@ Setting `UsePagedSqlQuery` to `False` your project will use the `Fetch` method ``` ## SqlPageSize -Specifying the `SqlPageSize` will change the size of the paged sql queries, by default the value is 1000. +Specifying the `SqlPageSize` will change the size of the paged SQL queries. The default value is 1000. ```json "Umbraco": { From 6d45f443122abbd7c6209569a2f6081f6bc242d4 Mon Sep 17 00:00:00 2001 From: Mole Date: Mon, 28 Oct 2024 10:51:33 +0100 Subject: [PATCH 08/17] Apply suggestions from code review Co-authored-by: sofietoft --- .../creating-custom-seed-key-provider.md | 20 +++++++++---------- .../reference/cache/cache-seeding.md | 5 ++--- 2 files changed, 12 insertions(+), 13 deletions(-) diff --git a/15/umbraco-cms/extending/creating-custom-seed-key-provider.md b/15/umbraco-cms/extending/creating-custom-seed-key-provider.md index bc9c6b17375..64fbd4ea869 100644 --- a/15/umbraco-cms/extending/creating-custom-seed-key-provider.md +++ b/15/umbraco-cms/extending/creating-custom-seed-key-provider.md @@ -4,21 +4,19 @@ description: A guide to creating a custom seed key provider for Umbraco # Creating a Custom Seed Key Provider -From version 15 and onwards Umbraco uses a lazy loaded cache, this means content is loaded into the cache on an as-needed basis. -However, you may some specific content to always be in the cache, to achieve this you can implement your own custom seed key providers. +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 is two types of seed key providers: `IDocumentSeedKeyProvider` for documents and `IMediaSeedKeyProvider` for media, -these interfaces are identical so only `IDocumentSeedKeyProvider` is demonstrated here. +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 themselves cached and only calculated once, this means that any documents created after the site has started won't be included in the seed keys untill ther server has restarted. +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. -First we'll create a class called `BlogSeedKeyProvider` that implements `IDocumentSeedKeyProvider`. +1. Create a new class called `BlogSeedKeyProvider` that implements `IDocumentSeedKeyProvider`. ```csharp using Umbraco.Cms.Infrastructure.HybridCache; @@ -51,7 +49,9 @@ public class BlogSeedKeyProvider : IDocumentSeedKeyProvider {...} ``` -Now we can parse a hardcoded string to a guid and use the `IDocumentNavigationQueryService` to get the children of the blog node and return their keys as a `HashSet`. +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() @@ -66,7 +66,7 @@ public ISet GetSeedKeys() return new HashSet(); } ``` -We since we're returning it as a set, and all the sets gets unioned, we don't have to worry about duplicates. +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: @@ -99,7 +99,7 @@ public class BlogSeedKeyProvider : IDocumentSeedKeyProvider ### Registering the Seed Key Provider -Now that we have implemented the `BlogSeedKeyProvider` we need to register it in the `Startup` class. +Now that the `BlogSeedKeyProvider` is implemented, it must be registered in the `Startup` class. ```csharp using MySite.SeedKeyProviders; @@ -112,4 +112,4 @@ builder.Services.AddSingleton(); {...} ``` -Now all our blogpost will be seeded into the cache on startup, and will always be present in the cache. +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 index d6b177f0a6a..c09cd4b5319 100644 --- a/15/umbraco-cms/reference/cache/cache-seeding.md +++ b/15/umbraco-cms/reference/cache/cache-seeding.md @@ -4,11 +4,10 @@ description: Information about cache seeding # Cache Seeding -From version 15 and onwards Umbraco uses a lazy loaded cache, this means content is loaded into the cache on an as-needed basis -that is whenever a piece of content is shown on the website for the first time it first needs to be loaded into the cache. +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. -However, for certain pages, for instance the front page, you may not want this delay to be there, the role of cache seeding is to solve this issue. +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 From 206efbef9cd8427f2b8f9770336a5b16f26b97a2 Mon Sep 17 00:00:00 2001 From: sofietoft Date: Wed, 30 Oct 2024 10:41:36 +0100 Subject: [PATCH 09/17] Update SUMMARY.md --- 15/umbraco-cms/SUMMARY.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/15/umbraco-cms/SUMMARY.md b/15/umbraco-cms/SUMMARY.md index 1f094aa78ee..eab26646e38 100644 --- a/15/umbraco-cms/SUMMARY.md +++ b/15/umbraco-cms/SUMMARY.md @@ -46,6 +46,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 @@ -69,7 +70,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) @@ -91,6 +92,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) From 023b5e6d319bc5d952abe8a35d5c7c25f8d84d89 Mon Sep 17 00:00:00 2001 From: sofietoft Date: Wed, 30 Oct 2024 10:42:56 +0100 Subject: [PATCH 10/17] Update .gitbook.yaml --- 15/umbraco-cms/.gitbook.yaml | 1 + 1 file changed, 1 insertion(+) 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 From 063c8229b1907aecc987e1df91b2ac7e5b1a1c01 Mon Sep 17 00:00:00 2001 From: sofietoft Date: Wed, 30 Oct 2024 10:45:06 +0100 Subject: [PATCH 11/17] Update release-candidate-guide.md --- 15/umbraco-cms/release-candidate-guide.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/15/umbraco-cms/release-candidate-guide.md b/15/umbraco-cms/release-candidate-guide.md index 26d11bc6e59..f545f93ba13 100644 --- a/15/umbraco-cms/release-candidate-guide.md +++ b/15/umbraco-cms/release-candidate-guide.md @@ -63,6 +63,9 @@ Here is a list of all the articles that are new to this version or have been upd ### New articles * [Tutorial: Extending the Help Menu](tutorials/extending-the-help-menu.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 From 12c0fc83fd11a61e94abbf8d59edb5d7bb5c75e9 Mon Sep 17 00:00:00 2001 From: sofietoft Date: Thu, 31 Oct 2024 09:40:00 +0100 Subject: [PATCH 12/17] Added note about missing NuCache Settings article --- 15/umbraco-cms/reference/configuration/cache-settings.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/15/umbraco-cms/reference/configuration/cache-settings.md b/15/umbraco-cms/reference/configuration/cache-settings.md index 86e1bfbb581..b5005c0fe15 100644 --- a/15/umbraco-cms/reference/configuration/cache-settings.md +++ b/15/umbraco-cms/reference/configuration/cache-settings.md @@ -4,6 +4,12 @@ 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](#nucachesettings). +{% endhint %} + ## 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. From dcf8a9c12647477a375509ccff4132a0324ba48e Mon Sep 17 00:00:00 2001 From: nikolajlauridsen Date: Thu, 31 Oct 2024 09:45:57 +0100 Subject: [PATCH 13/17] Add HybridCacheOptions section --- .../reference/configuration/cache-settings.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/15/umbraco-cms/reference/configuration/cache-settings.md b/15/umbraco-cms/reference/configuration/cache-settings.md index 86e1bfbb581..263016e8e9c 100644 --- a/15/umbraco-cms/reference/configuration/cache-settings.md +++ b/15/umbraco-cms/reference/configuration/cache-settings.md @@ -4,6 +4,34 @@ description: Information on the Cache settings section # Cache settings +## 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 if using property editors like the block grid, and multiple languages. +To try and avoid this Umbraco overrides this setting to 100MB by default, however 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. From b4f315cb4d62194c5819d331c35bb1e6ad439378 Mon Sep 17 00:00:00 2001 From: sofietoft Date: Thu, 31 Oct 2024 10:13:20 +0100 Subject: [PATCH 14/17] Tiny corrections to appease GitBook --- 15/umbraco-cms/reference/configuration/cache-settings.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/15/umbraco-cms/reference/configuration/cache-settings.md b/15/umbraco-cms/reference/configuration/cache-settings.md index b5005c0fe15..8dde1820393 100644 --- a/15/umbraco-cms/reference/configuration/cache-settings.md +++ b/15/umbraco-cms/reference/configuration/cache-settings.md @@ -2,12 +2,12 @@ description: Information on the Cache settings section --- -# Cache settings +# 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](#nucachesettings). +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 %} ## Seeding settings From 33240299ef8704338d94755bdfc2d7bdeeddc4cd Mon Sep 17 00:00:00 2001 From: Mole Date: Wed, 6 Nov 2024 08:58:36 +0100 Subject: [PATCH 15/17] Update 15/umbraco-cms/reference/configuration/cache-settings.md Co-authored-by: sofietoft --- 15/umbraco-cms/reference/configuration/cache-settings.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/15/umbraco-cms/reference/configuration/cache-settings.md b/15/umbraco-cms/reference/configuration/cache-settings.md index 83616e2f7a9..24c54401b27 100644 --- a/15/umbraco-cms/reference/configuration/cache-settings.md +++ b/15/umbraco-cms/reference/configuration/cache-settings.md @@ -16,9 +16,9 @@ Umbraco's cache is implemented using Microsofts `HybridCache`, which also has it ### 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 if using property editors like the block grid, and multiple languages. -To try and avoid this Umbraco overrides this setting to 100MB by default, however you can also configure this manually using a composer: +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; From c1148cde4e41ae793b3dc53f8bc5eea78f066567 Mon Sep 17 00:00:00 2001 From: sofietoft Date: Wed, 6 Nov 2024 09:28:16 +0100 Subject: [PATCH 16/17] Minor change to trigger GitBook checks --- 15/umbraco-cms/reference/configuration/cache-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/15/umbraco-cms/reference/configuration/cache-settings.md b/15/umbraco-cms/reference/configuration/cache-settings.md index 24c54401b27..ff942a1b770 100644 --- a/15/umbraco-cms/reference/configuration/cache-settings.md +++ b/15/umbraco-cms/reference/configuration/cache-settings.md @@ -90,7 +90,7 @@ The Entry settings allow you to specify how long cache entries should be kept. T ## LocalCacheDuration -Specifies the duration that cache entries should be kept in the local memory cache. The default value is 24 hours. +Specifies the duration for which cache entries should be kept in the local memory cache. The default value is 24 hours. ```json "Umbraco": { From fbf2b96ac8c0d765902207d27dc4dc3263e910ba Mon Sep 17 00:00:00 2001 From: sofietoft Date: Wed, 6 Nov 2024 09:32:39 +0100 Subject: [PATCH 17/17] GitBook checks --- 15/umbraco-cms/reference/configuration/cache-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/15/umbraco-cms/reference/configuration/cache-settings.md b/15/umbraco-cms/reference/configuration/cache-settings.md index ff942a1b770..ff396b51374 100644 --- a/15/umbraco-cms/reference/configuration/cache-settings.md +++ b/15/umbraco-cms/reference/configuration/cache-settings.md @@ -1,5 +1,5 @@ --- -description: Information on the Cache settings section +description: Information on the Cache settings section --- # Cache Settings