Interface IRoutineClient

Defines the contract for interacting with the Xperiflow Routine system.

Namespace: Workspace.XBR.Xperiflow.Routines

Assembly: Xperiflow.dll

Declaration

public interface IRoutineClient

Examples

Basic usage example:

// Create a new routine instance
var instance = routineClient.CreateRoutineInstanceAsync(
    "data-processing",
    "1.0.0",
    "Monthly Report Processing"
).Result;

// Monitor system load
var currentRuns = routineClient.GetCurrentRunsCountAsync().Result;
var memoryUsage = routineClient.GetCurrentMemoryUsageAsync().Result;

Remarks

The Workspace.XBR.Xperiflow.Routines.IRoutineClient provides the primary interface for programmatically interacting with the Xperiflow Routine system. It enables creating, monitoring, and managing Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstance objects and their associated operations.

Key Capabilities:

• System MonitoringMonitor current system load through run counts and memory usage

• Instance ManagementCreate, retrieve, and delete routine instances

• Flexible QueryingFind instances by identifier, name, or routine type

Implementation Notes:

Implementations should handle authentication, request/response processing, and error handling for communication with the Xperiflow Routine API. All methods support cancellation tokens and optional caching for improved performance.

Methods

GetCurrentRunsCountAsync(MemoizedCacheInfo?, CancellationToken)

Retrieves the current number of runs in a running state.

Declaration

Task<int> GetCurrentRunsCountAsync(MemoizedCacheInfo? cacheInfo = null, CancellationToken cancellationToken = default)

Remarks

This method provides insight into the current system load by returning the count of concurrently executing routine runs. This information can be used to make informed decisions about when to schedule new runs.

Returns

Task<System.Int32>

A task that represents the asynchronous operation. The task result contains the number of runs currently in a running state.

Parameters

Type	Name	Description
Workspace.XBR.Xperiflow.Utilities.Http.MemoizedCacheInfo	cacheInfo	Optional caching information to improve performance
System.Threading.CancellationToken	cancellationToken	Token to monitor for cancellation requests

Exceptions

Workspace.XBR.Xperiflow.Routines.RoutineClientException Thrown when an error occurs while retrieving the run count

GetCurrentMemoryUsageAsync(MemoizedCacheInfo?, CancellationToken)

Retrieves the current memory usage of the Routine system in gigabytes.

Declaration

Task<double> GetCurrentMemoryUsageAsync(MemoizedCacheInfo? cacheInfo = null, CancellationToken cancellationToken = default)

Remarks

This method provides the total memory consumption of all currently running routines. The returned value represents the actual memory usage in gigabytes and can be used to monitor system resource utilization.

Returns

Task<System.Double>

A task that represents the asynchronous operation. The task result contains the current memory usage in gigabytes.

Parameters

Type	Name	Description
Workspace.XBR.Xperiflow.Utilities.Http.MemoizedCacheInfo	cacheInfo	Optional caching information to improve performance
System.Threading.CancellationToken	cancellationToken	Token to monitor for cancellation requests

Exceptions

Workspace.XBR.Xperiflow.Routines.RoutineClientException Thrown when an error occurs while retrieving memory usage information

CreateRoutineInstanceAsync(string, string, string?, string, double?, IEnumerable<string>?, JObject?, MemoizedCacheInfo?, CancellationToken)

Creates a new routine instance with the specified parameters.

Declaration

Task<RoutineInstance> CreateRoutineInstanceAsync(string routineTypename, string routineVersion, string? name = null, string description = "", double? memoryOverride = null, IEnumerable<string>? labels = null, JObject? attributes = null, MemoizedCacheInfo? cacheInfo = null, CancellationToken cancellationToken = default)

Remarks

This method creates a new routine instance that can be used to execute the specified routine type. The routine type must exist in the Routine Library and the version must be available.

Returns

Task< Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstance >

A task that represents the asynchronous operation. The task result contains the newly created Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstance.

Parameters

Type	Name	Description
System.String	routineTypename	The name of the routine type. Must match a registered routine in the Routine Library
System.String	routineVersion	The version of the routine as a string (e.g., "1.0.0")
System.String	name	Optional user-friendly name for the routine instance
System.String	description	Optional description of the routine instance
System.Nullable<System.Double>	memoryOverride	Optional memory limit override in gigabytes
System.Collections.Generic.IEnumerable<System.String>	labels	Optional collection of labels to associate with the instance
Newtonsoft.Json.Linq.JObject	attributes	Optional JSON object containing custom attributes
Workspace.XBR.Xperiflow.Utilities.Http.MemoizedCacheInfo	cacheInfo	Optional caching information to improve performance
System.Threading.CancellationToken	cancellationToken	Token to monitor for cancellation requests

Exceptions

System.ArgumentException Thrown when routineTypename or routineVersion is invalid Workspace.XBR.Xperiflow.Routines.RoutineClientException Thrown when an error occurs during instance creation

CreateRoutineInstanceAsync(string, Version, string?, string, double?, IEnumerable<string>?, JObject?, MemoizedCacheInfo?, CancellationToken)

Creates a new routine instance with the specified parameters using a strongly-typed version.

Declaration

Task<RoutineInstance> CreateRoutineInstanceAsync(string routineTypename, Version routineVersion, string? name = null, string description = "", double? memoryOverride = null, IEnumerable<string>? labels = null, JObject? attributes = null, MemoizedCacheInfo? cacheInfo = null, CancellationToken cancellationToken = default)

Remarks

This overload provides the same functionality as the string-based version but accepts a System.Version object for type safety and better version validation.

Returns

Task< Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstance >

A task that represents the asynchronous operation. The task result contains the newly created Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstance.

Parameters

Type	Name	Description
System.String	routineTypename	The name of the routine type. Must match a registered routine in the Routine Library
System.Version	routineVersion	The version of the routine as a System.Version object
System.String	name	Optional user-friendly name for the routine instance
System.String	description	Optional description of the routine instance
System.Nullable<System.Double>	memoryOverride	Optional memory limit override in gigabytes
System.Collections.Generic.IEnumerable<System.String>	labels	Optional collection of labels to associate with the instance
Newtonsoft.Json.Linq.JObject	attributes	Optional JSON object containing custom attributes
Workspace.XBR.Xperiflow.Utilities.Http.MemoizedCacheInfo	cacheInfo	Optional caching information to improve performance
System.Threading.CancellationToken	cancellationToken	Token to monitor for cancellation requests

Exceptions

System.ArgumentNullException Thrown when routineTypename or routineVersion is null System.ArgumentException Thrown when routineTypename is invalid Workspace.XBR.Xperiflow.Routines.RoutineClientException Thrown when an error occurs during instance creation

DeleteRoutineInstanceAsync(string, MemoizedCacheInfo?, CancellationToken)

Deletes the specified routine instance.

Declaration

Task DeleteRoutineInstanceAsync(string instanceIdentifier, MemoizedCacheInfo? cacheInfo = null, CancellationToken cancellationToken = default)

Remarks

This method permanently deletes the routine instance and all associated data. The operation cannot be undone. Active runs associated with the instance may be affected by this operation.

Returns

System.Threading.Tasks.Task

A task that represents the asynchronous delete operation

Parameters

Type	Name	Description
System.String	instanceIdentifier	The unique identifier of the routine instance to delete
Workspace.XBR.Xperiflow.Utilities.Http.MemoizedCacheInfo	cacheInfo	Optional caching information to improve performance
System.Threading.CancellationToken	cancellationToken	Token to monitor for cancellation requests

Exceptions

System.ArgumentException Thrown when instanceIdentifier is null or empty Workspace.XBR.Xperiflow.Routines.RoutineClientException Thrown when an error occurs during deletion or the instance is not found

GetRoutineInstanceAsync(string, MemoizedCacheInfo?, CancellationToken)

Retrieves a routine instance by its unique identifier.

Declaration

Task<RoutineInstance?> GetRoutineInstanceAsync(string instanceIdentifier, MemoizedCacheInfo? cacheInfo = null, CancellationToken cancellationToken = default)

Remarks

This method retrieves a routine instance by its unique identifier. If the instance does not exist, the method returns null rather than throwing an exception.

Returns

Task< Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstance >

A task that represents the asynchronous operation. The task result contains the Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstance if found, or null if not found.

Parameters

Type	Name	Description
System.String	instanceIdentifier	The unique identifier of the routine instance to retrieve
Workspace.XBR.Xperiflow.Utilities.Http.MemoizedCacheInfo	cacheInfo	Optional caching information to improve performance
System.Threading.CancellationToken	cancellationToken	Token to monitor for cancellation requests

Exceptions

System.ArgumentException Thrown when instanceIdentifier is null or empty Workspace.XBR.Xperiflow.Routines.RoutineClientException Thrown when an error occurs during retrieval

GetRoutineInstanceByNameAsync(string, MemoizedCacheInfo?, CancellationToken)

Retrieves a routine instance by its user-friendly name.

Declaration

Task<RoutineInstance?> GetRoutineInstanceByNameAsync(string instanceName, MemoizedCacheInfo? cacheInfo = null, CancellationToken cancellationToken = default)

Remarks

This method retrieves a routine instance by its user-friendly name. If multiple instances have the same name, the behavior is implementation-defined. If no instance with the specified name exists, the method returns null.

Returns

Task< Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstance >

A task that represents the asynchronous operation. The task result contains the Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstance if found, or null if not found.

Parameters

Type	Name	Description
System.String	instanceName	The name of the routine instance to retrieve
Workspace.XBR.Xperiflow.Utilities.Http.MemoizedCacheInfo	cacheInfo	Optional caching information to improve performance
System.Threading.CancellationToken	cancellationToken	Token to monitor for cancellation requests

Exceptions

System.ArgumentException Thrown when instanceName is null or empty Workspace.XBR.Xperiflow.Routines.RoutineClientException Thrown when an error occurs during retrieval

GetRoutineInstancesByTypenameAsync(string, MemoizedCacheInfo?, CancellationToken)

Retrieves all routine instances of the specified routine type.

Declaration

Task<List<RoutineInstance>> GetRoutineInstancesByTypenameAsync(string routineTypename, MemoizedCacheInfo? cacheInfo = null, CancellationToken cancellationToken = default)

Remarks

This method retrieves all routine instances that match the specified routine type. If no instances of the specified type exist, an empty list is returned.

Returns

Task<System.Collections.Generic.List{Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstance}>

A task that represents the asynchronous operation. The task result contains a list of Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstance objects matching the specified type.

Parameters

Type	Name	Description
System.String	routineTypename	The name of the routine type to filter by
Workspace.XBR.Xperiflow.Utilities.Http.MemoizedCacheInfo	cacheInfo	Optional caching information to improve performance
System.Threading.CancellationToken	cancellationToken	Token to monitor for cancellation requests

Exceptions

System.ArgumentException Thrown when routineTypename is null or empty Workspace.XBR.Xperiflow.Routines.RoutineClientException Thrown when an error occurs during retrieval