NewLife.AntJob 5.1.2026.1028

NewLife.AntJob - Ant Scheduling

🌐 简体中文 | 繁體中文 | Español | Deutsch | 日本語 | Français | Português | Русский | 한국어 | العربية

AntJob is a distributed task and real-time data scheduling platform built purely in .NET: any large job is split into parallel time/data slices, dispatched to elastic worker nodes, retried on failure and replayed for backfill, with a web console for live monitoring.

Open source: https://github.com/NewLifeX/AntJob
Tutorial: https://newlifex.com/blood/antjob
Live demo (hosted environment): http://ant.newlifex.com

Contents: Quick Start · Main Features · Ecosystem Map · Documentation · Contributing · Team · License

Quick Start

Install

dotnet add package NewLife.AntJob

Template (recommended)

dotnet new install NewLife.Templates
# Create a project with an AntJob sample
dotnet new antjob --name TestJob
cd TestJob
dotnet run

Minimal example

The following source code is located in Samples/HisAgent. Create a .NET Core 3.1+ project and reference AntJob from NuGet. Instantiate a Scheduler and configure a network provider.

using AntJob;
using HisAgent;
using NewLife.Log;
using NewLife.Model;
using Stardust;

// Enable console logging and intercept all exceptions
XTrace.UseConsole();

var services = ObjectContainer.Current;
services.AddStardust();

services.AddAntJob()
    .AddHandler<HelloJob>();

// Friendly shutdown
var host = services.BuildHost();
await host.RunAsync();

Add the first scheduled job handler:

using System;
using AntJob;

internal class HelloJob : Handler
{
    public HelloJob() => Job.Cron = "7/30 * * * * ?";

    public override Int32 Execute(JobContext ctx)
    {
        // Time of the current task
        var time = ctx.Task.DataTime;
        WriteLog("NewLife AntJob! Current task time: {0}", time);
        return 1; // Number of successfully processed items
    }
}

Job handlers must inherit Handler and override Execute to implement business logic. The Time and Step set in the constructor are only used for the first registration; later changes are made in the console.

Or use an asynchronous scheduled job handler:

using System;
using AntJob;

internal class HelloJob : Handler
{
    public HelloJob() => Job.Cron = "7/30 * * * * ?";

    public override async Task<Int32> ExecuteAsync(JobContext ctx)
    {
        using var span = Tracer?.NewSpan("HelloJob", ctx.Task.DataTime);

        // Time of the current task
        var time = ctx.Task.DataTime;
        WriteLog("NewLife AntJob! Current task time: {0}", time);
        if (!ctx.Task.Data.IsNullOrEmpty()) WriteLog("Data: {0}", ctx.Task.Data);

        var state = Rand.NextString(16);
        var http = new HttpClient { BaseAddress = new Uri("https://newlifex.com") };
        http.SetUserAgent();
        var rs = await http.GetAsync<IDictionary<String, Object>>("/cube/info", new { state });

        if (rs.TryGetValue("state", out var value) && value is String str)
        {
            Trace.Assert(state == str, "Returned state does not match");
        }

        // Number of successfully processed items
        return 1;
    }
}

Run it

On the first run it automatically tries to connect to tcp://127.0.0.1:9999 and tcp://ant.newlifex.com:9999 (active/standby), based on the AntSetting configuration. If Server is configured with an http(s):// address, it automatically switches to the HTTP channel and receives downstream notifications over WebSocket.

Log example:

21:33:08.470  1 N - Start job scheduling engine [AntJob.Providers.NetworkJobProvider], jobs [1], timer 5s
21:33:08.471  1 N - HelloJob start work False range (2020-04-09 00:00:00, 0001-01-01 00:00:00) Offset=15 Step=10 MaxTask=8

Web console and reset

Deploy AntJob.Web (IIS / Kestrel / Docker) and then change the client's Server setting to point at its service address. No separate AntServer is required:

{
  "Ant": {
    "Server": "https://ant.example.com",
    "AppId": "MyJobApp",
    "Secret": ""
  }
}

After the client logs in, it establishes a long-lived /AntJob/Notify WebSocket connection through HTTP heartbeats to receive job-change and message-arrival notifications; when WebSocket is unavailable, it still works on the polling interval. Once a job is enabled in the console, the scheduling center slices tasks by time point and dispatches them: you can view task details, retry errors and batch-reset tasks to recompute history. Run several Agents to scale out — any given task is executed by exactly one node, and failures are retried according to policy.

Local file scheduling only

When NetworkJobProvider is not configured, the default local Provider is used, which is suitable for offline debugging on a single machine.

Docker (illustrative)

No official image is provided yet; you can package one inside your organization:

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app
COPY ./publish/ .
ENTRYPOINT ["dotnet","AntJob.Web.dll"]

Deployment topologies

Main Features

AntJob uses the "ants moving house" idea to split any large task into small pieces that can run in parallel. The idea was born in Lujiazui, Shanghai, during the 2008 financial crisis, in response to financial institutions' urgent need for low-cost, high-efficiency data analysis. Comparable systems include XxlJob, Quartz, Hangfire, Airflow (in some scenarios) and self-built scheduled-script clusters; AntJob emphasizes "data/time slicing + retry + unified multiple modes" and non-intrusive integration with an enterprise's existing .NET ecosystem, validated by trillion-scale scheduling and tens of billions of data-cleaning records.

<details> <summary><b>Typical Use Cases</b> (4)</summary>

</details>

<details> <summary><b>Core Capabilities</b> (11)</summary>

</details>

<details> <summary><b>Scheduling Modes</b> (5)</summary>

</details>

<details> <summary><b>Architecture and Core Modules</b> (9)</summary>

</details>

<details> <summary><b>Reliability and Consistency</b> (6)</summary>

</details>

<details> <summary><b>Configuration</b> (7)</summary>

</details>

<details> <summary><b>Extension Mechanisms</b> (6)</summary>

</details>

<details> <summary><b>Performance and Capacity Planning</b> (7)</summary>

</details>

<details> <summary><b>Core Concepts</b> (5)</summary>

</details>

<details> <summary><b>Comparison with Other Schedulers</b> (4)</summary>

</details>

<details> <summary><b>FAQ</b> (5)</summary>

</details>

<details> <summary><b>v4 Upgrade Progress</b> (5)</summary>

</details>

<details> <summary><b>Roadmap Beyond v4</b> (4)</summary>

</details>

Architecture diagrams

Component topology

+----------------------+            +-------------------------+
|  Execution Node(Agent)|  RPC/TCP  |  Scheduling Center(Server)|
|  - Scheduler         |            | - JobService / Task     |
|  - Handlers(business)|            | - State & metadata      |
+----------+-----------+            +-----------+-------------+
           |  Sync logs/tracing (optional Stardust)  |
           v
    +-------------+      Web UI / API      +------------------+
    | DB / Storage|  <------------------>  | Web Console AntWeb|
    +-------------+                         +------------------+

Job application (implements IJob)

sequenceDiagram
    participant App as Job Application
    participant Server as Scheduling Center AntServer
    participant Web as Console AntWeb

    App->>Server: app login
    Note over Server: app/secret
    App-->>Server: register job

    Web->>Server: set parameters
    Web->>Server: start job

    App->>Server: request job task
    Server-->>App: return task
    Note over App: multi-threaded task processing

    App-->>Server: report partial status
    Note over Web: job status dashboard
    App->>Server: processing succeeded
    App-->>Server: processing failed
    App-->>Server: delayed processing

Scheduling-center master/slave architecture

sequenceDiagram
    participant App1 as Job Application
    participant Server1 as Scheduling Center
    participant DB as Database
    participant Server2 as Scheduling Center 2
    participant App2 as Job Application 2
    participant App3 as Job Application 3
    participant App4 as Job Application 4
    participant Web as Web Console

    App1->>Server1: login
    Server1->>DB: connect
    App1-->>Server2: failover
    Server2->>DB: connect

    App2->>Server1: login
    App3->>Server1: login
    App4->>Server1: login

    Web-->>Server1: monitor

Ecosystem Map

NewLife is a layered ecosystem of independently versioned open-source projects. The map below is shared verbatim by every NewLife repository; each project links to its repository and its primary NuGet package.

Project	What it does	Downloads
Foundation
NewLife.Core	Logging, configuration, caching, networking, serialization, scheduling and APM tracing.
NewLife.XCode	Data middleware: single tables at the tens-of-billions scale, automatic sharding, read-write splitting, 10+ databases.
NewLife.Net	High-performance network library: 1.77M pps / 14.5 Gbps on a single machine (TCP 1KB, 2026-10), 4M long-lived TCP connections.
NewLife.Remoting	Protocol communication and RPC framework for client/server applications and IoT devices.
NewLife.Agent	Installs .NET applications as OS daemons: Windows services and Linux systemd.
NewLife.Templates	dotnet new project templates for console, web, API, service, data and IoT projects.
Data & Messaging
NewLife.Redis	Redis client with microsecond latency, millions of ops/s and built-in message queues.
NewLife.RocketMQ	Pure managed RocketMQ client for Apache RocketMQ and Alibaba Cloud Message Queue.
NewLife.MQTT	MQTT client and server, including Alibaba Cloud IoT connectivity.
NewLife.NovaDb	Hybrid database in C#: embedded or networked, relational, time-series, message queue and KV in one.
NewLife.MySql	MySql driver and helper layer built on the NewLife data stack.
Web, AI & Distributed
NewLife.Cube	Rapid admin-platform framework: permissions, SSO, OAuth server and CRUD scaffolding.
Stardust	Distributed service platform: node management, APM, configuration center, registry and release center.
AntJob	Distributed task and real-time data scheduling platform with sharding, retries and backfill.
NewLife.AI	Unified client for 46 LLM providers plus ChatAI, a ready-to-run web chat application.
Industrial & IoT
NewLife.IoT	IoT standard library defining protocol contracts and device abstractions.
NewLife.Modbus	Modbus TCP/RTU/ASCII implementation on top of NewLife.IoT.
NewLife.Siemens	Siemens PLC protocol on top of NewLife.IoT.
NewLife.Omron	Omron PLC protocol on top of NewLife.IoT.
NewLife.Melsec	Mitsubishi Melsec PLC protocol on top of NewLife.IoT.
NewLife.OPC	OPC client for industrial data access.	—
NewLife.BACnet	BACnet building-automation protocol stack.
ZeroIoT	Lightweight open-source IoT platform with gateway and device management.	—
Vehicle Telematics
NewLife.JT808	JT/T 808 vehicle positioning protocol: 70+ message bodies, 2011/2013/2019.
NewLife.JT809	JT/T 809 platform-to-platform protocol for transport authorities.
NewLife.JT1078	JT/T 1078 in-vehicle video: RTP parsing, FLV/fMP4 remuxing and live streaming.
Domain Components
NewLife.Office	One package for Excel, Word, PPT, PDF and 15+ document formats.
NewLife.Audio	Cross-platform audio: codecs, device I/O, DSP, containers and streaming.
NewLife.Video	Video codecs, container formats, frame processing and streaming.
NewLife.Map	Unified interface over Baidu, AMap, Tencent and Tianditu with geocoding and coordinate conversion.
NewLife.IP	IPv4 geolocation with an offline memory-mapped database and an online API fallback.
Tools & Products
CrazyCoder	Developer toolbox: network, serial port, crypto, regex, Modbus and MQTT.
GitCandy	Self-hosted Git source code management system.	—
LuckyClover	Installs the matching .NET runtime automatically when launched from an older host.	—

Badges show the primary package of each project; theme, extension and satellite packages are listed on their NuGet pages. The 30+ packages not listed here (FTP, LoRa, Office extensions, protocol drivers and more) are available under the NewLifeX organization and on newlifex.com. This table is maintained in the NewLife.Core README.

Documentation

• Tutorial: https://newlifex.com/blood/antjob
• Live demo: http://ant.newlifex.com
• Multi-language README rules: Doc/多语言本地化.md

Contributing

Build and test

dotnet build -c Release
dotnet test -c Release
# Only the main test project (net10.0), used by CI on win-x64 and linux-arm64
dotnet test AntTest/AntTest.csproj -c Release

• CI: .github/workflows/test.yml builds, runs tests and checks localization plus the README language switcher
• README checks: pwsh -File sync-readme-languages.ps1 -Check, pwsh -File sync-readme-package.ps1 -Check and pwsh -File check-readme-structure.ps1
• Benchmarks: Benchmark/AntJob.Benchmarks (BenchmarkDotNet)

Repository layout

AntJob/                 Client core library
AntJob.Extensions/      Extension handlers/messages/SQL, etc.
AntJob.Server/          Scheduling-center core service logic (JobService, etc.)
AntJob.Web/             Razor Pages + Cube admin console
AntJob.Data/            Base data models (entity layer)
Samples/                Sample projects (HisAgent, HisData, HisWeb, HelloWork)
AntTest/                Unit/integration tests
Doc/                    Documentation and assets

Release

Push a v-prefixed tag (for example v5.0.2026.1024) to trigger .github/workflows/publish.yml. The workflow packs AntJob, AntJob.Extensions and AntJob.Web, publishes them to NuGet.org and GitHub Packages, and creates a GitHub Release whose notes are taken from the matching ChangeLog.md section (assets include nupkg and snupkg). A manual run only publishes packages and does not create a Release. Commits touching AntJob/ or AntJob.Extensions/ on master also produce beta packages through publish-beta.yml.

Feedback

• Before submitting, make sure dotnet build and the relevant tests pass; follow the repository code style.
• Report bugs and suggestions via Issue; Stars and PRs are welcome.

Team

<img src="https://github.com/NewLifeX/AntJob/raw/master/Doc/ant.png" width="96" align="left" alt="AntJob" />

<img src="https://newlifex.com/logo.png" width="48" align="right" alt="NewLife" />

Founded in 2002, the NewLife team has spent more than two decades on the .NET and IoT ecosystem, maintains nearly 100 open-source projects (34 of them core to this map), and delivers integrated software and hardware solutions for power, logistics, healthcare, industrial control and internet industries. We live by the motto "learning has no seniority — mastery earns respect".

Open-source components have been downloaded 6.48M times from NuGet (ecosystem-wide, as of 2026-10).

Website: https://newlifex.com · Open source organization: https://github.com/NewLifeX

<details> <summary>WeChat Official Account: 智能大石头 (scan to follow)</summary>

</details>

License

This project is licensed under MIT © 2002-2026 NewLife Team. You may use, modify and redistribute it freely.

If this project is helpful to you, welcome to Star it, share it with your team, or provide improvement suggestions via Issue/PR.