Processes

Work that takes longer than a request should, such as copying a large branch or importing a feed, runs as a process. The command starts it and answers at once. The CMS interface shows the process with its progress, and the user can pause or cancel it.

commands.Register("shop.reprice", ctx => {
    var p = ctx.Payload<RepriceRequest>();              // check first: a mistake is the command's answer
    var ids = ctx.Db.Query<IProduct>().Where(x => x.Brand == p.Brand).SelectId().Execute().ToArray();
    return ctx.StartProcess(new CmsProcessStart("shop.reprice", "Repricing " + p.Brand) {
        Description = ids.Length + " products, " + p.Percent + " % up.",
    }, async (c, process) => {
        for (var i = 0; i < ids.Length; i++) {
            await process.CheckpointAsync();             // a pause holds here, and a cancel stops here
            var product = c.Db.Get<IProduct>(ids[i]);
            product.Price *= 1 + p.Percent / 100m;
            c.Db.Update(product);
            c.Changed(product.Id, product.Meta.NodeTypeId, CmsApiChangeKind.Updated);
            process.Report(i + 1, ids.Length, (i + 1) + " of " + ids.Length + " repriced");
        }
        return new { repriced = ids.Length };          // the result, in the process's snapshot
    }).Snapshot();
});

A process belongs to the user who started it. It keeps running after they sign out, and they see it again when they sign back in. Other users cannot see it. Processes live in memory, so a server restart loses them. A finished process is kept until the user dismisses it, or for a day.

Its own context. The work runs in the background with a context of its own, c: the same user, store, payload and options as the command, but no request (c.Http throws). It is cancelled with the process.
Changes. The nodes noted with c.Changed(…) reach connected clients at each checkpoint and at the end, so an editor sees the work as it goes.
Checkpoints. Call CheckpointAsync() between steps, never inside a transaction. A pause takes hold there, so the longer a step, the longer the process says "Pausing". After a cancel it throws OperationCanceledException, which ends the process as cancelled. Any other exception fails it, with the exception's message.
Progress. Report(done, total, status) says how far the work has come, with total null while it is unknown.
No stopping half-way. Work that must not stop part-way sets CanPause = false or CanCancel = false on its CmsProcessStart.

State	Means
`running`	the work goes on
`pausing`, `paused`	a pause was asked for and waits for the next checkpoint; then the work is held there
`cancelling`	a cancel was asked for and waits for the next checkpoint
`completed`, `failed`, `cancelled`	finished: with its `result`, with its `error`, or stopped