ktsu.IntervalAction 1.8.0

Prefix Reserved
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package ktsu.IntervalAction --version 1.8.0
                    
NuGet\Install-Package ktsu.IntervalAction -Version 1.8.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="ktsu.IntervalAction" Version="1.8.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="ktsu.IntervalAction" Version="1.8.0" />
                    
Directory.Packages.props
<PackageReference Include="ktsu.IntervalAction" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add ktsu.IntervalAction --version 1.8.0
                    
#r "nuget: ktsu.IntervalAction, 1.8.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package ktsu.IntervalAction@1.8.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=ktsu.IntervalAction&version=1.8.0
                    
Install as a Cake Addin
#tool nuget:?package=ktsu.IntervalAction&version=1.8.0
                    
Install as a Cake Tool

ktsu.IntervalAction

A .NET library that provides a simple way to execute an action at a specified interval.

License NuGet Version NuGet Version NuGet Downloads GitHub commit activity GitHub contributors GitHub Actions Workflow Status

Introduction

IntervalAction is a .NET library that provides a simple and flexible way to execute an action at a specified interval. It offers precise control over execution timing, various interval types, and easy management of scheduled actions. Designed for scenarios where you need recurring tasks like polling, background processing, or timed updates.

Features

  • Flexible Timing: Execute actions at precise intervals
  • Interval Types: Choose between running intervals from last start or last completion
  • Configurable Polling: Fine-tune polling frequency for better performance
  • Immediate Execution: Option to execute actions immediately on start
  • Start/Stop Control: Easily pause and restart scheduled actions
  • Thread Safety: Safe for concurrent access from multiple threads
  • Low Overhead: Minimal resource usage during idle periods
  • Supports .NET 8.0 and .NET 9.0: Modern .NET support

Installation

Package Manager Console

Install-Package ktsu.IntervalAction

.NET CLI

dotnet add package ktsu.IntervalAction

Package Reference

<PackageReference Include="ktsu.IntervalAction" Version="x.y.z" />

Usage Examples

Basic Example

using ktsu.IntervalAction;

var intervalAction = IntervalAction.Start(new()
{
    Action = () => Console.WriteLine("Hello, World!"),
    ActionInterval = TimeSpan.FromSeconds(1),
    PollingInterval = TimeSpan.FromMilliseconds(100), // Optional, default is 1 second
    IntervalType = IntervalType.FromLastStart // Optional, default is FromLastCompletion
});

// An action will execute immediately and then every second
// outputting "Hello, World!" to the console until stopped

intervalAction.Stop();

// The action will no longer execute until you call Restart()

intervalAction.Restart();

Using FromLastCompletion Interval Type

using ktsu.IntervalAction;

var intervalAction = IntervalAction.Start(new()
{
    Action = () =>
    {
        Console.WriteLine($"Action started at: {DateTimeOffset.Now}");
        // Simulate a task that takes some time to complete
        Task.Delay(500).Wait();
        Console.WriteLine($"Action completed at: {DateTimeOffset.Now}");
    },
    ActionInterval = TimeSpan.FromSeconds(2),
    PollingInterval = TimeSpan.FromMilliseconds(100),
    IntervalType = IntervalType.FromLastCompletion // Waits until the action completes before starting the interval timer
});

// The action will execute immediately and then every 2 seconds after the previous execution completes

Handling Long-Running Tasks

using ktsu.IntervalAction;

var intervalAction = IntervalAction.Start(new()
{
    // AsyncAction, not Action: an async lambda assigned to Action becomes async void, which
    // returns at its first await, so runs would overlap and exceptions would crash the process
    AsyncAction = async cancellationToken =>
    {
        Console.WriteLine("Starting long-running task...");
        
        // Simulate a long-running task; the token is cancelled by Stop()
        await Task.Delay(5000, cancellationToken);
        
        Console.WriteLine("Long-running task completed");
    },
    ActionInterval = TimeSpan.FromSeconds(10),
    IntervalType = IntervalType.FromLastCompletion // Important for long-running tasks
});

// For cleanup when done
await Task.Delay(60000); // Run for 1 minute

// StopAsync cancels the token, then waits for the run in progress to finish, so nothing the
// action uses is disposed while it is still running. Stop() returns without waiting.
await intervalAction.StopAsync();
intervalAction.RethrowExceptions(); // Reports a failure from the final run, if there was one

Dynamic Interval Adjustment

using ktsu.IntervalAction;

// Create with initial settings
var options = new IntervalActionOptions
{
    Action = () => Console.WriteLine($"Tick at {DateTime.Now}"),
    ActionInterval = TimeSpan.FromSeconds(5)
};

var intervalAction = IntervalAction.Start(options);

// Later, adjust the interval
await Task.Delay(20000); // After 20 seconds

// Takes effect from the next poll, measured from the last run. The action keeps running.
intervalAction.ChangeInterval(TimeSpan.FromSeconds(1));

Console.WriteLine("Interval changed to 1 second");

API Reference

IntervalAction Class

The main class for scheduling recurring actions.

It implements IDisposable.

Methods
Name Parameters Return Type Description
Start IntervalActionOptions options IntervalAction Static factory method to create and start an interval action
Stop void Stops the scheduled action from running; a run already in progress is not waited for. An async action's token is cancelled on the thread pool, so its cancellation cleanup never runs on, or blocks, the caller's thread
StopAsync Task Stops the scheduled action, then completes once the polling loop has exited and any run in progress has finished. Use it before disposing anything the action uses. Called from inside the action, it does not wait for the run it is called from, so the action can stop its own polling
Restart void Restarts a previously stopped action
RestartAsync Task Restarts a previously stopped action, completing once the new polling loop has started
ChangeInterval TimeSpan actionInterval void Changes the interval of a running action. It applies from the next poll and is measured from the last run, and a run in progress is not interrupted
RethrowExceptions void Rethrows the exception the action last failed with, if any
Dispose void Stops the action for good, like Stop, after which Restart throws ObjectDisposedException. An instance that is never stopped or disposed keeps running even when nothing references it

IntervalActionOptions Class

Configuration options for an interval action.

Properties
Name Type Description
Action Action The action to execute at intervals (set this or AsyncAction)
AsyncAction Func<CancellationToken, Task> An asynchronous action to execute at intervals; a run lasts until its task completes, and the token is cancelled by Stop() (set this or Action)
ActionInterval TimeSpan The interval between executions (required)
PollingInterval TimeSpan How frequently to check if action should run (optional, default 1 second; must be between 1 ms and int.MaxValue ms, about 24.8 days)
IntervalType IntervalType Determines how intervals are measured (optional, default FromLastCompletion)

IntervalType Enum

Defines how the interval is measured.

Value Description
FromLastCompletion The interval starts after the action has completed
FromLastStart The interval starts when the action begins executing

Contributing

Contributions are welcome! Here's how you can help:

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Please make sure to update tests as appropriate and adhere to the existing coding style.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Versioning

Check the CHANGELOG.md for detailed release notes and version changes.

Acknowledgements

Special thanks to all contributors and the .NET community for their support.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on ktsu.IntervalAction:

Package Downloads
ktsu.KtsuTools.BuildMonitor

KtsuTools is a unified developer tools suite that consolidates multiple ktsu-dev utilities into a single CLI application with consistent UX powered by Spectre.Console.

ktsu.KtsuTools.MemFrag

KtsuTools is a unified developer tools suite that consolidates multiple ktsu-dev utilities into a single CLI application with consistent UX powered by Spectre.Console.

ktsu.KtsuTools.Machine

KtsuTools is a unified developer tools suite that consolidates multiple ktsu-dev utilities into a single CLI application with consistent UX powered by Spectre.Console.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.8.1-pre.1 56 11/16/2026
1.8.0 158 11/14/2026
1.7.1 104 11/13/2026
1.7.1-pre.2 65 11/12/2026
1.7.1-pre.1 54 11/11/2026
1.7.0 244 11/11/2026
1.6.1-pre.1 84 10/8/2026
1.6.0 1,167 10/8/2026
1.5.3 200 10/7/2026
1.5.2 198 10/7/2026
1.5.1 321 10/6/2026
1.5.0 212 10/5/2026
1.4.7-pre.1 68 10/5/2026
1.4.6 1,439 10/5/2026
1.4.5 297 9/29/2026
1.4.4 253 9/29/2026
1.4.4-pre.1 73 9/28/2026
1.4.3 255 9/28/2026
1.4.2 253 9/27/2026
1.4.1 961 9/23/2026
Loading failed

## v1.8.0 (minor)

Changes since v1.7.0:

- Add ChangeInterval to change a running action's interval [minor] (#109) (matt-edmondson)
- Cancel the async action's token off the caller's thread in Stop [patch] (#110) (matt-edmondson)