Document URL Cache: Ensure URLs are rebuilt after upgrade and prevent duplicate initialization (closes #21337)

[AndyButland]

Description

This PR addresses the document URL cache not being populated correctly after upgrade from v13 to v17 (reported in #21337).

We currently have a step in the migration process itself to rebuild the document URL cache (RebuildDocumentUrls). For some reason - and to be honest, I haven't been able to identify why - this only picks up a small subset of the available documents. As such only a few URLs are written to the database, and when the URL cache is populated on start up it only retrieves and prepares the cache for these.

I found if rather than rebuilding the URLs, we remove the key value that stores the URL generation method, the normal start-up handler will kick-in and handle this correctly. This compares the stored value with the currently registered URL provider, and if it differs, will trigger a rebuild of the URLs.

So in other words, moving the URL build to after the completion of the migration resolves the issue - all URLs are generated and stored in the database, and thus all are available for caching.

As I say, I haven't figured out why it doesn't work in the migration stage, but it's not too surprising as at this point Umbraco hasn't fully booted so may be missing something for URL generation.

Empirically though I can demonstrate the fix works.

In addition I noticed that we were rebuilding the document URL cache twice, even with this fix in place. With a lot URLs, this could be expensive, so I've added a second fix to prevent this happening, such that we only call it once.

Change Summary

Issue 1: URLs not generated during migration

The RebuildDocumentUrls migration was calling InitAsync during the migration phase when it's not possible to gather all document URLs. This caused only a small subset of URLs to be generated.

Fix: Clear the UmbracoUrlGeneration key during migration instead of calling InitAsync. This forces a rebuild on first normal startup when all services are fully initialized.

Issue 2: Duplicate InitAsync calls

After migration, InitAsync was being called twice:

1. By ContentCacheRefresher when MigrationPlanExecutor.RebuildCache() triggers RefreshAllPublishedSnapshot()
2. By DocumentUrlServiceInitializerNotificationHandler on UmbracoApplicationStartingNotification

Fix: Added IsInitialized property to IDocumentUrlService and check it in the notification handler to skip if already initialized.

Log File Analysis

The following log file extracts show the results of the fixes:

Initial state

Note that we only build and cache 2 URLs, and the caching operation runs 3 times:

[09:57:50 INF] Execute RebuildDocumentUrls
[09:57:50 INF] Rebuilding all document URLs.
[09:57:50 INF] Caching document URLs.
[09:57:50 INF] Cached 2 document URLs.
...
[09:57:54 INF] Starts rebuilding the cache. This can be a long running operation
[09:57:55 INF] Document cache seeding completed in 34 ms with 58 seed keys.
[09:57:55 INF] Caching document URLs.
[09:57:55 INF] Cached 2 document URLs.
...
[09:57:55 INF] Database configuration status: <p>Upgrade completed!</p>
[09:57:55 INF] Caching document URLs.
[09:57:55 INF] Cached 2 document URLs.

After fix to ensure all URLs are bult

Note now we rebuild all URLs, but we still run the caching phase twice.

[10:00:52 INF] Starts rebuilding the cache. This can be a long running operation
[10:00:52 INF] Document cache seeding completed in 33 ms with 58 seed keys.
[10:00:52 INF] Rebuilding all document URLs.
[10:00:52 INF] Caching document URLs.
[10:00:53 INF] Cached 229 document URLs.
...
[10:00:53 INF] Database configuration status: <p>Upgrade completed!</p>
[10:00:53 INF] Caching document URLs.
[10:00:53 INF] Cached 229 document URLs.

After second fix to avoid second running of URL caching

Note now we rebuild all URLs, and only cache once.

[10:20:23 INF] Starts rebuilding the cache. This can be a long running operation
[10:20:23 INF] Document cache seeding completed in 33 ms with 58 seed keys.
[10:20:23 INF] Rebuilding all document URLs.
[10:20:23 INF] Caching document URLs.
[10:20:23 INF] Cached 229 document URLs.
...
[10:20:23 INF] Database configuration status: <p>Upgrade completed!</p>

After second fix with normal start up

Note no rebuild but URLs are cached

[10:22:05 INF] Acquiring MainDom.
[10:22:05 INF] Acquired MainDom.
[10:22:06 INF] Caching document URLs.
[10:22:06 INF] Cached 229 document URLs

After second fix with change to definition of registered URL providers

Note rebuild and URLs are cached. This I could fake by running this on the database:

update umbracoKeyValue
set value = ''
where [key] = 'UmbracoUrlGeneration'

[10:46:46 INF] Acquiring MainDom.
[10:46:47 INF] Acquired MainDom.
[10:46:47 INF] Rebuilding all document URLs.
[10:46:48 INF] Caching document URLs.
[10:46:48 INF] Cached 224 document URLs.

Testing

Upgrade a 13 database to 17 and verify that all expected document URLs are persisted to umbracoDocumentUrl and cached such that they are usable on the front-end and display in the backoffice.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

[Zeegaan]

Had to rerun a flaky test, but looks good to me 🚀