Merge branch 'main' into cms/database-availability-checks

Author: AndyButland

10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/nested-content.md

@@ -4,6 +4,8 @@
 We highly recommend that you use the [Block List](block-editor/block-list-editor.md) instead.
 
 Nested Content has been marked as obsolete and development on the property editor has been discontinued.
+
+[Umbraco Deploy](https://docs.umbraco.com/umbraco-deploy/deployment-workflow/import-export/import-with-migrations) and [uSync migrations](https://github.com/Jumoo/uSyncMigrations) have support for migrating from nested content to the block list.
 {% endhint %}
 
 `Alias: Umbraco.NestedContent`
@@ -106,7 +108,7 @@ Example:
             // Render your content, e.g. item.Value<string>("heading")
         }
     }
-    
+
 }
 ```
 
@@ -176,31 +178,31 @@ Afterwards, the entire list needs to be serialized to Json via JsonConvert.
 @using Newtonsoft.Json;
 @inject IContentService _contentService;
 
- //if the class containing our code inherits SurfaceController, UmbracoApiController, 
+ //if the class containing our code inherits SurfaceController, UmbracoApiController,
  //or UmbracoAuthorizedApiController, we can get ContentService from Services namespace
- var contentService = _contentService; 
+ var contentService = _contentService;
 //here we create a new node, and fill out attendeeList afterwards
- IContent request = contentService.Create("new node", guid, "mydoctype", -1); 
+ IContent request = contentService.Create("new node", guid, "mydoctype", -1);
  //our list which will contain nested content
- var attendees = new List<Dictionary<string, string>>(); 
+ var attendees = new List<Dictionary<string, string>>();
 //participants is our list of attendees - multiple items, good use case for nested content
- foreach (var person in participants) 
+ foreach (var person in participants)
             attendees.Add(new Dictionary<string, string>() {
             //this is the only "default" value we need to fill for nested item
-            {"ncContentTypeAlias","attendee"}, 
+            {"ncContentTypeAlias","attendee"},
             {"user_name", person.name},
             {"user_email",person.user_email},
-            {"join_time",person.join_time.ToString()}, 
+            {"join_time",person.join_time.ToString()},
             //we convert some properties to String just to be on the safe side
             {"leave_time",person.leave_time.ToString()},
             {"duration",person.duration.ToString()},
             {"phone",person.phone.ToString()}
             });
             }
             //bind the attendees List to attendeeList property on the newly created content node
-            request.SetValue("attendeeList", JsonConvert.SerializeObject(attendees)); 
+            request.SetValue("attendeeList", JsonConvert.SerializeObject(attendees));
             //Save the entire node via ContentService
-            ContentService.SaveAndPublish(request); 
+            ContentService.SaveAndPublish(request);
 ```
 
 In the above sample we iterate through a list of participants (the data for such participants could be coming from an API, for example), and add a new `Dictionary` item for each person in the list.

13/umbraco-cms/SUMMARY.md

@@ -368,6 +368,7 @@
 * [Cache & Distributed Cache](reference/cache/README.md)
   * [Accessing the cache](reference/cache/application-cache.md)
   * [ICacheRefresher](reference/cache/icacherefresher.md)
+  * [IMemberPartialViewCacheInvalidator](reference/cache/imemberpartialviewcacheinvalidator.md)
   * [IServerMessenger](reference/cache/iservermessenger.md)
   * [Getting/Adding/Updating/Inserting Into Cache](reference/cache/updating-cache.md)
   * [Examples](reference/cache/examples/README.md)

13/umbraco-cms/extending/packages/example-package-repository.md

@@ -30,7 +30,7 @@ When the next major version of Umbraco is released, we'll test and either extend
 
 ### Tests Project
 
-We have a [project for unit tests](https://github.com/umbraco/Umbraco.AuthorizedServices/tree/main/tests/Umbraco.AuthorizedServices.Tests) in `tests/<ProjectName>.Tests`.  It contains references to `Umbraco.Cms.Tets` and a project reference to the package:
+We have a [project for unit tests](https://github.com/umbraco/Umbraco.AuthorizedServices/tree/main/tests/Umbraco.AuthorizedServices.Tests) in `tests/<ProjectName>.Tests`.  It contains references to `Umbraco.Cms.Tests` and a project reference to the package:
 
 ```xml
 <ProjectReference Include="..\..\src\Umbraco.AuthorizedServices\Umbraco.AuthorizedServices.csproj" />

13/umbraco-cms/reference/cache/imemberpartialviewcacheinvalidator.md

@@ -0,0 +1,37 @@
+# Partial view cache refresher for members
+
+This section describes the `IMemberPartialViewCacheInvalidator` interface, what it's default implementation does and how to customize it.
+
+## What is an IMemberPartialViewCacheInvalidator?
+
+This interface is used to isolate the logic that invalidates parts of the partial view cache when a member is updated.
+
+## Why do we need to partially invalidate the partial view cache?
+
+Razor templates may show data that is retrieved from a member object. Those templates might be cached by using the partial caching mechanism (for example, `@await Html.CachedPartialAsync("member",Model,TimeSpan.FromDays(1), cacheByMember:true)`). When a member is updated, these cached partials must be invalidated to ensure updated data is shown.
+
+## Where is it used?
+
+This interface is called from the member cache refresher (`MemberCacheRefresher`), which is invoked every time a member is updated.
+
+## Details of the default implementation
+
+Razor template partials are cached through a call to `Html.CachedPartialAsync` with `cacheByMember` set to `true`. This will append the ID of the currently logged-in member with a marker to the partial view cache key.  For example, `-m1015-`.
+
+When the `ClearPartialViewCacheItems` method is called it will clear all cache items that match the marker for the updated members.
+
+If no member is logged in during caching, items with an empty member marker (for example, `-m-`) are also cleared.
+
+## Customizing the implementation
+
+You can replace the default implementation by removing it and registering your own in a composer.
+
+```csharp
+public class ReplaceMemberCacheInvalidatorComposer : IComposer
+{
+    public void Compose(IUmbracoBuilder builder)
+    {
+        builder.Services.AddUnique<IMemberPartialViewCacheInvalidator, MyCustomMemberPartialViewCacheInvalidator>();
+    }
+}
+```

13/umbraco-cms/reference/security/external-login-providers.md

@@ -151,6 +151,8 @@ In those cases, it would mean that anyone who has a Google or Facebook account c
 
 If auto-linking for public providers such as these was needed you would need to limit the access. This can be done by domain or other information provided in the claims using the options/callbacks specified in those provider's authentication options.
 
+When auto-linking for the backoffice you will want to define what user groups the user will be part of. This is done via the `defaultUserGroups` parameter provided to the constructor of `ExternalSignInAutoLinkOptions` (see example below). If the value is not set the user will by default be added to the Editors group.
+
 ### Auto-linking on Member authentication
 
 Auto-linking on Member authentication only makes sense if you have a public member registration already or the provider does not have public account creation.

13/umbraco-cms/reference/using-ioc.md

@@ -18,7 +18,7 @@ There are different strategies for registering your dependencies and not one str
 
 In this article, we will cover the following three strategies:
 
-* [Registering dependencies in the `Program.cs` file](#registering-dependencies-in-the-programcs-file)
+* [Registering dependencies in the `Program.cs` file](#registering-dependencies-in-the-program.cs-file)
 * [Registering dependencies in a composer](#registering-dependencies-in-a-composer)
 * [Registering dependencies in bundles](#registering-dependencies-in-bundles)
 

14/umbraco-cms/reference/security/external-login-providers.md

@@ -155,6 +155,8 @@ In those cases, it would mean that anyone who has a Google or Facebook account c
 
 If auto-linking for public providers such as these was needed you would need to limit the access. This can be done by domain or other information provided in the claims using the options/callbacks specified in those provider's authentication options.
 
+When auto-linking for the backoffice you will want to define what user groups the user will be part of. This is done via the `defaultUserGroups` parameter provided to the constructor of `ExternalSignInAutoLinkOptions` (see example below). If the value is not set the user will by default be added to the Editors group.
+
 #### Is your project hosted on Umbraco Cloud?
 
 Umbraco Cloud uses Umbraco ID for all authentication, including access to the Umbraco Backoffice.

14/umbraco-cms/reference/using-ioc.md

@@ -18,7 +18,7 @@ There are different strategies for registering your dependencies and not one str
 
 In this article, we will cover the following three strategies:
 
-* [Registering dependencies in the `Program.cs` file](#registering-dependencies-in-the-programcs-file)
+* [Registering dependencies in the `Program.cs` file](#registering-dependencies-in-the-program.cs-file)
 * [Registering dependencies in a composer](#registering-dependencies-in-a-composer)
 * [Registering dependencies in bundles](#registering-dependencies-in-bundles)
 

15/umbraco-cms/SUMMARY.md

@@ -252,6 +252,7 @@
 * [Custom File Systems (IFileSystem)](extending/filesystemproviders/README.md)
   * [Using Azure Blob Storage for Media and ImageSharp Cache](extending/filesystemproviders/azure-blob-storage.md)
 * [Configuring Azure Key Vault](extending/key-vault.md)
+* [Server Events From SignalR](extending/server-events.md)
 * [Packages](extending/packages/README.md)
   * [Creating a Package](extending/packages/creating-a-package.md)
   * [Language file for packages](extending/packages/language-files-for-packages.md)

15/umbraco-cms/extending/server-events.md

@@ -0,0 +1,118 @@
+---
+description: Describes server events emitted via a SignalR hub and available for consumption in the backoffice
+---
+
+# Server Events
+
+Umbraco registers a SignalR event hub that broadcasts events related to the update of entities. These can be used in the backoffice to respond to changes made by users other than the current editor.
+
+Each server event is triggered via a notification handler. So for example, when a document is saved, the `ContentSavedNotification` is published. This is handled by a class responsible for issuing a server event.
+
+Not all server events should be broadcast to all users. For example, if a user doesn't have access to the Media section, they shouldn't receive notifications on updates to media. For core entities, Umbraco uses the same permission system that defines access in the backoffice. In this way, only events appropriate for the currently logged in editor are exposed.
+
+## Event Information
+
+Each event emitted contains the following fields:
+
+- `EventType` - the event type, which might be `Created`, `Updated`, `Deleted` etc.
+- `EventSource` - the event source, which might be `Document`, `Media` etc.
+- `Key` - the unique GUID that identifies the entity changed.
+
+## Event Authorization
+
+The currently authorized user will have one or more claims indicating the access they have to different areas of the backoffice. When first connecting to the SignalR hub, these details are used to assign the user to one or more SignalR groups.
+
+Which groups they have access to is determined by the collection of registered `IEventSourceAuthorizer` instances.
+
+For example, there is a `DocumentEventAuthorizer` that ensures users with access to the documents (content) tree are assigned to the `Umbraco:CMS:Document` event source.  As a result, when server events are emitted for documents, only those users with this access will receive them.
+
+## Extending Server Events
+
+Using the same patterns as the core CMS, server events for other entities defined in packages or custom solutions can be emitted.
+
+Firstly, a `IEventSourceAuthorizer` should be registered. This will likely hook into what you already have in place for controlling access to the backoffice section where the entity is managed.
+
+For example, if you had a `Product` entity managed in a custom CMS section, the authorizer might look like this:
+
+```csharp
+using Microsoft.AspNetCore.Authorization;
+using Umbraco.Cms.Core;
+using Umbraco.Cms.Web.Common.Authorization;
+
+public class ProductEventAuthorizer : EventSourcePolicyAuthorizer
+{
+    public ProductEventAuthorizer(IAuthorizationService authorizationService)
+      : base(authorizationService)
+    {
+    }
+
+    public override IEnumerable<string> AuthorizableEventSources => ["Umbraco:Custom:Product"];
+
+    protected override string Policy => "TreeAccessProducts"; // Maps to an existing authorization policy
+                                                              // used in an [Authorize] attribute.
+}
+```
+
+The authorizer should be registered with Umbraco using something like the following, called from a composer, or otherwise in application start up:
+
+```csharp
+public static IUmbracoBuilder AddCustomAuthorizers(this IUmbracoBuilder builder)
+{
+    builder.EventSourceAuthorizers()
+        .Append<ProductEventAuthorizer>();
+}
+```
+
+You then need to emit the event from a notification handler which handles notifications published when the entity is updated.
+
+For example, assuming an existing `ProductSavedNotification` that is published with the product is saved:
+
+```csharp
+using Umbraco.Cms.Core;
+using Umbraco.Cms.Core.Events;
+using Umbraco.Cms.Core.Models.Entities;
+using Umbraco.Cms.Core.Models.ServerEvents;
+using Umbraco.Cms.Core.Notifications;
+using Umbraco.Cms.Core.ServerEvents;
+
+namespace Umbraco.Cms.Api.Management.ServerEvents;
+
+public class ProductServerEventSender : INotificationAsyncHandler<ProductSavedNotification>
+{
+    private readonly IServerEventRouter _serverEventRouter;
+
+    public ProductServerEventSender(IServerEventRouter serverEventRouter) => _serverEventRouter = serverEventRouter;
+
+    public async Task HandleAsync(ProductSavedNotification notification, CancellationToken cancellationToken) =>
+        await NotifySavedAsync(notification, "Umbraco:Custom:Product");
+
+    private async Task NotifySavedAsync<T>(SavedNotification<T> notification, string source)
+        where T : IEntity
+    {
+        foreach (T entity in notification.SavedEntities)
+        {
+            var eventModel = new ServerEvent
+            {
+                EventType = entity.CreateDate == entity.UpdateDate
+                    ? Constants.ServerEvents.EventType.Created : Constants.ServerEvents.EventType.Updated,
+                Key = entity.Key,
+                EventSource = source,
+            };
+
+            await _serverEventRouter.RouteEventAsync(eventModel);
+        }
+    }
+}
+```
+
+Again, the notification handler will need to be registered with Umbraco:
+
+```csharp
+public static IUmbracoBuilder AddCustomEvents(this IUmbracoBuilder builder)
+{
+    builder.AddNotificationAsyncHandler<ProductSavedNotification, ProductServerEventSender>();
+}
+```
+
+
+