TaskOptions.cs

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

using System.Collections.Immutable;

namespace Microsoft.DurableTask;

/// <summary>
/// Options that can be used to control the behavior of orchestrator task execution.
/// </summary>
public record TaskOptions
{
    /// <summary>
    /// Initializes a new instance of the <see cref="TaskOptions"/> class.
    /// </summary>
    /// <param name="retry">The task retry options.</param>
    public TaskOptions(TaskRetryOptions? retry)
        : this(retry, null)
    {
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="TaskOptions"/> class.
    /// </summary>
    /// <param name="retry">The task retry options.</param>
    /// <param name="tags">The tags to associate with the task.</param>
    public TaskOptions(TaskRetryOptions? retry = null, IDictionary<string, string>? tags = null)
    {
        this.Retry = retry;
        this.Tags = tags;
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="TaskOptions"/> class by copying from another instance.
    /// </summary>
    /// <param name="options">The task options to copy from.</param>
    public TaskOptions(TaskOptions options)
    {
        Check.NotNull(options);
        this.Retry = options.Retry;
        this.Tags = options.Tags;
        this.Version = options.Version;
    }

    /// <summary>
    /// Gets the task retry options.
    /// </summary>
    public TaskRetryOptions? Retry { get; init; }

    /// <summary>
    /// Gets the tags to associate with the task.
    /// </summary>
    public IDictionary<string, string>? Tags { get; init; }

    /// <summary>
    /// Gets the version to associate with the scheduled task.
    /// </summary>
    /// <remarks>
    /// <para>
    /// When <c>null</c> (the default), the task inherits the version of the orchestration instance that is
    /// scheduling it.
    /// </para>
    /// <para>
    /// When non-<c>null</c> (including <see cref="TaskVersion.Unversioned"/>), the task is scheduled with the
    /// specified version explicitly, overriding any inherited version.
    /// </para>
    /// <para>
    /// The receiving worker is responsible for resolving the scheduled version to a registered implementation
    /// according to its own versioning configuration. That resolution is not visible to the scheduling client.
    /// </para>
    /// <para>
    /// When deploying versioned workloads, treat each worker's versioning configuration as a deployment-time
    /// policy: the same version value may dispatch to different registrations across deployments. Use the
    /// worker's startup and per-dispatch diagnostic logs to verify behavior across environments.
    /// </para>
    /// </remarks>
    public TaskVersion? Version { get; init; }

    /// <summary>
    /// Returns a new <see cref="TaskOptions" /> from the provided <see cref="RetryPolicy" />.
    /// </summary>
    /// <param name="policy">The policy to convert from.</param>
    /// <returns>A <see cref="TaskOptions" /> built from the policy.</returns>
    public static TaskOptions FromRetryPolicy(RetryPolicy policy) => new(policy);

    /// <summary>
    /// Returns a new <see cref="TaskOptions" /> from the provided <see cref="AsyncRetryHandler" />.
    /// </summary>
    /// <param name="handler">The handler to convert from.</param>
    /// <returns>A <see cref="TaskOptions" /> built from the handler.</returns>
    public static TaskOptions FromRetryHandler(AsyncRetryHandler handler) => new(handler);

    /// <summary>
    /// Returns a new <see cref="TaskOptions" /> from the provided <see cref="RetryHandler" />.
    /// </summary>
    /// <param name="handler">The handler to convert from.</param>
    /// <returns>A <see cref="TaskOptions" /> built from the handler.</returns>
    public static TaskOptions FromRetryHandler(RetryHandler handler) => new(handler);

    /// <summary>
    /// Returns a new <see cref="SubOrchestrationOptions" /> with the provided instance ID. This can be used when
    /// starting a new sub-orchestration to specify the instance ID.
    /// </summary>
    /// <param name="instanceId">The instance ID to use.</param>
    /// <returns>A new <see cref="SubOrchestrationOptions" />.</returns>
    public SubOrchestrationOptions WithInstanceId(string instanceId) => new(this, instanceId);
}

/// <summary>
/// Options that can be used to control the behavior of orchestrator task execution. This derived type can be used to
/// supply extra options for orchestrations.
/// </summary>
public record SubOrchestrationOptions : TaskOptions
{
    /// <summary>
    /// Initializes a new instance of the <see cref="SubOrchestrationOptions"/> class.
    /// </summary>
    /// <param name="retry">The task retry options.</param>
    /// <param name="instanceId">The orchestration instance ID.</param>
    public SubOrchestrationOptions(TaskRetryOptions? retry = null, string? instanceId = null)
        : base(retry)
    {
        this.InstanceId = instanceId;
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="SubOrchestrationOptions"/> class.
    /// </summary>
    /// <param name="options">The task options to wrap.</param>
    /// <param name="instanceId">The orchestration instance ID.</param>
    public SubOrchestrationOptions(TaskOptions options, string? instanceId = null)
        : base(options)
    {
        this.InstanceId = instanceId;
        if (options is SubOrchestrationOptions derived && instanceId is null)
        {
            this.InstanceId = derived.InstanceId;
        }
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="SubOrchestrationOptions"/> class by copying from another instance.
    /// </summary>
    /// <param name="options">The sub-orchestration options to copy from.</param>
    public SubOrchestrationOptions(SubOrchestrationOptions options)
        : base(options)
    {
        Check.NotNull(options);
        this.InstanceId = options.InstanceId;
    }

    /// <summary>
    /// Gets the orchestration instance ID.
    /// </summary>
    public string? InstanceId { get; init; }

    /// <summary>
    /// Gets the version to associate with the sub-orchestration instance.
    /// </summary>
    /// <remarks>
    /// Forwards to <see cref="TaskOptions.Version"/>. This property is declared on the derived
    /// record to preserve binary compatibility with assemblies compiled against earlier SDK versions
    /// that declared <c>SubOrchestrationOptions.Version</c> directly. New code should prefer
    /// <see cref="TaskOptions.Version"/>.
    /// </remarks>
    public new TaskVersion? Version
    {
        get => base.Version;
        init => base.Version = value;
    }
}

/// <summary>
/// Options for submitting new orchestrations via the client.
/// </summary>
public record StartOrchestrationOptions
{
    /// <summary>
    /// Initializes a new instance of the <see cref="StartOrchestrationOptions"/> class.
    /// </summary>
    /// <param name="InstanceId">
    /// The unique ID of the orchestration instance to schedule. If not specified, a new GUID value is used.
    /// </param>
    /// <param name="StartAt">
    /// The time when the orchestration instance should start executing. If not specified or if a date-time in the past
    /// is specified, the orchestration instance will be scheduled immediately.
    /// </param>
#pragma warning disable SA1313 // Parameter names should begin with lower-case letter - using PascalCase to maintain backward compatibility with positional record syntax
    public StartOrchestrationOptions(string? InstanceId = null, DateTimeOffset? StartAt = null)
#pragma warning restore SA1313
    {
        this.InstanceId = InstanceId;
        this.StartAt = StartAt;
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="StartOrchestrationOptions"/> class by copying from another instance.
    /// </summary>
    /// <param name="options">The start orchestration options to copy from.</param>
    public StartOrchestrationOptions(StartOrchestrationOptions options)
    {
        Check.NotNull(options);
        this.InstanceId = options.InstanceId;
        this.StartAt = options.StartAt;
        this.Tags = options.Tags;
        this.Version = options.Version;
        this.DedupeStatuses = options.DedupeStatuses;
    }

    /// <summary>
    /// Gets the unique ID of the orchestration instance to schedule. If not specified, a new GUID value is used.
    /// </summary>
    public string? InstanceId { get; init; }

    /// <summary>
    /// Gets the time when the orchestration instance should start executing. If not specified or if a date-time in the past
    /// is specified, the orchestration instance will be scheduled immediately.
    /// </summary>
    public DateTimeOffset? StartAt { get; init; }

    /// <summary>
    /// Gets the tags to associate with the orchestration instance.
    /// </summary>
    public IReadOnlyDictionary<string, string> Tags { get; init; } = ImmutableDictionary.Create<string, string>();

    /// <summary>
    /// Gets the version to associate with the orchestration instance.
    /// </summary>
    public TaskVersion? Version { get; init; }

    /// <summary>
    /// Gets the orchestration runtime statuses that should be considered for deduplication.
    /// </summary>
    /// <remarks>
    /// For type-safe usage, use the WithDedupeStatuses extension method.
    /// </remarks>
    public IReadOnlyList<string>? DedupeStatuses { get; init; }
}