v17.5.0-rc1

This is a release candidate for 17.5.0. It is published to NuGet as a prerelease, so you need to include prereleases to install it.

The main work in 17.5.0 is support for load-balanced sites, and a much better Publisher content and media browser. It also fixes restore points hanging on large sites under IIS.

Added

• Publisher: load-balanced targets are now handled properly. A push or pull is a conversation of several requests, and a load balancer could move it from one server to another partway through, which broke it in ways that were hard to diagnose. Publisher now keeps the conversation on one server, and reports clearly when that isn't possible instead of failing later with an unrelated error.
• Publisher: new uSync:Publisher:Settings:AffinityFailFast setting (off by default) stops a push or pull as soon as it moves to a different server, instead of letting it carry on.
• New uSync:WorkingFolder:Path setting controls where uSync keeps its working files, so all the servers in a load-balanced site can share one working folder.
• Publisher: the content and media browsers have a list view alongside the grid. Every item shows whether it is in sync, out of sync or missing on the other server.
• Publisher: the browsers now page through large folders (previously only the first 50 items were shown). You can also sort by name, type or last update, and search the current folder by name. Refreshing the page keeps your place.
• Publisher: an optional server identifier in the backoffice header shows which server you are logged into, using its name, icon and colour. Turn it on with "Show server identifier" in the server's settings. A new "Apply server colour to navbar" setting (on by default) controls the existing navbar colouring.
• Publisher: servers added through the Add server dialog start with a random colour and the server identifier turned on. Existing servers keep their current appearance.
• Publisher: servers now tell each other which features they support, so a push or pull can adapt to what the other server understands.

Load-balanced sites

A push or pull sends a series of requests to the target site. Each request uses files the one before it left in the target's working folder. When the target is load balanced, those requests can land on different servers. The working files are then missing on the server that picks up a request, and the push or pull fails partway through with a "File not found" or "Folder missing" error.

17.5.0 gives you two ways to deal with this. You can use either one, or both.

[!NOTE] If your load balancer already uses server affinity, you probably won't need to change any configuration in Umbraco: uSync's affinity support is on by default.

Server affinity (on by default)

If your load balancer uses an affinity cookie (ARR affinity on Azure App Service, Application Gateway, or any other cookie-based "sticky session" option), Publisher now picks the cookie up from the first response. It then sends it back on every later request of the same push or pull, so the whole operation stays on the server that answered first.

Setup: turn on cookie-based affinity in your load balancer. There's nothing to set in uSync. It works with any cookie name and does nothing against a server that doesn't set one. These settings are there if you need them:

"uSync": {
  "Publisher": {
    "Settings": {
      "AffinityEnabled": true,
      "AffinityCookieNames": [],
      "AffinityFailFast": false
    }
  }
}

• AffinityCookieNames: leave it empty to send back every cookie the target sets. Only list names if the target sets other cookies that should be left alone.
• AffinityFailFast: if a push or pull moves to a different server anyway, uSync always logs a warning naming both servers. Turn this on to also stop the operation there, instead of letting it fail a few steps later.

To see which server answered a request, check the X-uSync-Node header on responses from the target.

A shared working folder

Affinity is only needed because each server keeps its working files on its own local temp storage. If every server can reach the same storage (a UNC share, a mounted volume, or on Azure a path backed by Azure Files), you can put uSync's working folder there. Then every server sees the same files, whichever one answers a request.

"uSync": {
  "WorkingFolder": {
    "Path": "\\\\shared-server\\usyncwork"
  }
}

Setup:

• Set the same Path on every server in the site. It accepts an absolute path, or a path relative to the site's content root (e.g. ~/usyncwork), but a relative path is only shared if that location is itself on shared storage.
• The account the site runs as needs read, write and delete access to the folder on every server.
• The folder holds uploaded packs and in-progress imports, so give it room for your largest push or pull.
• Expect pushes and pulls to be a bit slower. Network storage is usually slower than a server's local disk, and every step reads and writes its working files there. If your load balancer supports affinity, that avoids the extra cost.
• The path is read when the site starts. Restart each server after you change it.
• The temp folder cleanup runs on every server, and each one sweeps the shared folder. That's expected: they all use the same cut-off, and a folder that another server has already removed is simply skipped.

Leave Path unset and nothing changes: uSync keeps using a uSync folder in Umbraco's local temp storage.

If the source site is load balanced too

The backoffice you push or pull from still needs your load balancer's normal session affinity for your browser. uSync doesn't manage that.

For the live progress connection on a load-balanced site, see the next section.

Server-to-server SignalR (live progress)

During a push or pull, the servers keep a SignalR connection open between them to send live progress back to your browser. In this release that connection gives up quickly on a server it can't reach, rather than waiting SignalR's default 15 seconds. The server settings page also warns you when it can't connect.

The connection only carries progress updates, so a push or pull works without it. You can turn it off:

"uSync": {
  "Publisher": {
    "Settings": {
      "ServerToServerHub": false
    }
  }
}

It is on by default, and you only need to turn it off if you see delays or other problems during a push or pull. This is most likely on a load-balanced site, where the connection can land on a different server from the push or pull itself.

Fixed

• Snapshots / restore points: creating a restore point on a large site no longer hangs when the site runs out of process under IIS (290). Content and media are now exported in pages over several requests, instead of one long request that IIS gives up on after its request timeout.
• Temp folder cleanup now runs on every server in a load-balanced site. Previously it only ran on the server that ran scheduled tasks.
• Publisher: the browser and its Compare dialog could match every item in a folder against the first changed item, and show the wrong status or comparison.
• Snapshots: labels no longer appear as raw keys (e.g. uSyncSnapshots_singleWarning) in the backoffice.
• The unsaved-changes dialog no longer has a Cancel option that did the same as closing it, and the remaining options are clearer.

For developers

• Polymorphic processing options are now registered with an explicit discriminator, to match Jumoo.Processing. This only matters if you have your own IProcessingOptions implementation.