# Nexus

> Background jobs and queues for .NET

## Docs

- [Admin UI](https://nexus.commercemind.se/admin-ui.md): Bundled as embedded resources in the CommerceMind.Nexus.UI NuGet package is an admin UI. It uses the API for all data and requests, so anything that's possible to do in the admin UI is possible to do with the API.
- [Nexus HTTP API](https://nexus.commercemind.se/api.md): A REST API for all Nexus features are included, and it's what the admin UI uses. The API is not enabled by default but all you need to do to enable it is:
- [Nexus MCP](https://nexus.commercemind.se/api/mcp.md): CommerceMind.Nexus.Mcp exposes Nexus operations as an MCP HTTP server. It is intended for tools and agents that need to inspect or operate Nexus jobs, queues, functions, health checks, and instances without calling the REST API directly.
- [Nexus vs Function as a Service](https://nexus.commercemind.se/faas.md): If you're reading the this documentation you might be thinking "well I can do this with scheduled Azure Functions and Azure Service Bus without any need for something like Nexus".
- [Database](https://nexus.commercemind.se/general/database.md): The system uses a SQL database to store meta data and queue messages. At the time of writing we support SQLite, Postgres and SQL Server. Feel free to reach out to us if you need support for another database engine like MySQL or MariaDB.
- [Dependency injection and scopes](https://nexus.commercemind.se/general/dependency-injection.md): Most operational Nexus services are scoped in v3. Jobs, functions, queue operations, health checks, and integrations can use scoped application dependencies, including a DbContext. The scope that resolves a service owns its lifetime.
- [Nexus v2 to v3 upgrade skill](https://nexus.commercemind.se/general/detailed-upgrade-guide.md): Upgrade applications using CommerceMind.Nexus from v2 to v3, including code, dependency injection, queue activation, Entity Framework, API clients, and deployment preparation.
- [Hangfire vs Nexus](https://nexus.commercemind.se/general/hangfire-vs-nexus.md): Hangfire is a great library for background processing and there's a lot of similarities between Hangfire and Nexus. Nexus Functions was built with Hangfire as an inspiration and it's especially the Functions part of Nexus and Hangfire that have a lot of similarities.
- [Hosting](https://nexus.commercemind.se/general/hosting.md): The service is built to allow both running as a continous background service as well as a service that periodically starts up, executes outstanding jobs and then exits.
- [Instance events](https://nexus.commercemind.se/general/instance-events.md): Nexus is built to work on multiple instances/servers at the same time in a scaled out environment. You can have as many servers running jobs as you like and the system still guarantees that a single job will only run on a single instance at any given time while distributed queue processors can process different leased messages on every instance. Leases prevent simultaneous selection during the lease period; expired leases and retries can cause repeated processing.
- [Nexus and JSON](https://nexus.commercemind.se/general/json.md): Nexus uses System.Text.Json by default to serialize persisted messages, job parameters, function arguments, instance events, and other state. Applications using Newtonsoft.Json converters can install CommerceMind.Nexus.NewtonsoftJson and call AddNexus().AddNewtonsoftJson() instead. Choose the serializer deliberately and check existing persisted data before switching.
- [Metrics with Open Telemetry](https://nexus.commercemind.se/general/metrics.md): Nexus exposes a number of metrics using Open Telemetry. Open Telemetry is an open standard for exposing metrics and telemetry that can be plugged into almost any monitoring service such as Azure Application Insights, Splunk, Elastic APM etc.
- [Monitoring](https://nexus.commercemind.se/general/monitoring.md): Nexus provides health checks, instance heartbeats, job-run logs/progress, queue statistics, and OpenTelemetry metrics. Use health checks for the current operational status and metrics for throughput and timing over time.
- [3.0.1](https://nexus.commercemind.se/general/release-notes.md): (3.0.0 didn't contain a rename of QueueAttribute.KeepProcessedMessagesFor, upgrade directly to 3.0.1 and skip 3.0.0)
- [Rollback from v3 to v2](https://nexus.commercemind.se/general/rollback-v3.md): The scripts below reverse the built-in Nexus 3.0 database upgrade for PostgreSQL and SQL Server. Nexus automatically captures a v2 rollback checkpoint during the first upgrade, before queue initialization or regular migrations change the database. You do not need to remember to run a separate capture script. The rollback restores the v2 schema and saved settings while retaining messages and job history written since the upgrade.
- [From v2 to v3](https://nexus.commercemind.se/general/upgrade-guide.md): Version 3 changes how queue processing is started and adds distributed queue processors and named queues. There are also breaking changes to service lifetimes, public APIs, and database initialization. Note that v3 renames some tables and values. Read more in Database initialization in v3.
- [Healthchecks](https://nexus.commercemind.se/healthchecks.md): Nexus integrates with and extends Health checks in ASP.NET Core.
- [Slack integration](https://nexus.commercemind.se/healthchecks/slack.md): If you're using Slack you can use the CommerceMind.Nexus.Slack NuGet package to get realtime updates when jobs and queues are failing. The package contains a IHealthCheckPublisher implementation that publishes health check failures to Slack.
- [Health check statistics](https://nexus.commercemind.se/healthchecks/statistics.md): The result of all Nexus health checks are stored when they go from one health status to another or when the description returned from the check changes. This means that if you click on a health check in the Admin UI you get statistics about when the health check status changed and for how long the period was when it was unhealthy or degraded.
- [Microsoft Teams integration](https://nexus.commercemind.se/healthchecks/teams.md): If you're using Teams you can use the CommerceMind.Nexus.Teams NuGet package to get realtime updates when jobs, queues, and health checks are failing. The package contains an IHealthCheckPublisher implementation that publishes health check failures to Teams through a Teams bot.
- [Introduction](https://nexus.commercemind.se/index.md): Background jobs, functions and queues for .NET.
- [Jobs overview](https://nexus.commercemind.se/jobs.md): An ordinary scheduled job is a C# class that implements IScheduledJob. Queue jobs use IQueueJob or IBatchQueueJob and can start when messages are ready instead of using a schedule. Both are registered through AddJobs(). Distributed queue processors are a separate alternative without job runs.
- [Job logs](https://nexus.commercemind.se/jobs/logs.md): Nexus has a ILoggerProvider which will collect logs by job run and store in the database.
- [Jobs with parameters](https://nexus.commercemind.se/jobs/parameters.md): In some situations it is useful for a job to take parameters
- [Job progress](https://nexus.commercemind.se/jobs/progress.md): Some jobs are expected to take a long time to complete and for such jobs it's nice to be able to see the progress for the job. Nexus has built-in support for jobs to report their progress through the IJobProgress interface like this:
- [Functions overview](https://nexus.commercemind.se/nexus-functions.md): Nexus functions are a lightweight way of executing a method on a service in the background. Sometimes you want to execute some method but you want it to run in the background. Either because the method takes a long time or because you want to make sure that it's retried until it completes successfully.
- [Functions vs Jobs & Queues](https://nexus.commercemind.se/nexus-functions/when-to-use.md): If you've already read about jobs and queues you might ask yourself "when should I use functions and when should I use jobs and queues?".
- [Queue activation](https://nexus.commercemind.se/queues/activation.md): Queue activation records that a queue may contain work ready to process. It lets a queue job start after enqueueing without a cron schedule or a separate start request. Repeated requests are coalesced per queue, so a burst of messages does not create a separate job run for every enqueue.
- [Processing directly from Azure Service Bus topics](https://nexus.commercemind.se/queues/azure.md): Nexus allows you to use Azure Service Bus as an external pending storage, which means that Nexus reads and processes messages directly from Service Bus without first storing them in an SQL-backed Nexus queue.
- [Enqueueing from outside the processing host](https://nexus.commercemind.se/queues/enqueueing.md): A website or API can produce messages while a separate Nexus application processes them. Share the message contract and stable queue names between the applications. There are three ways to publish.
- [Entity Framework with Nexus queues](https://nexus.commercemind.se/queues/entity-framework.md): If you're using Entity Framework you might want to sync your SaveChangesAsync() calls with calls to EnqueueAsync() on Nexus queues to ensure that they are committed together.
- [External pending queue storage](https://nexus.commercemind.se/queues/external-pending.md): The great thing about Nexus is the control and insight you get into queue messages from using an SQL based queue storage. But for some cases the message throughput is just too high for it to make sense to use SQL based queues for everything.
- [Filterable message properties](https://nexus.commercemind.se/queues/filterable.md): In some cases you might want to find messages where one or more property contains certain values. Like if you have a queue of inventory messages and you don't want to process it until the article data has come in. If your inventory message class looks like this:
- [Auto generated queues](https://nexus.commercemind.se/queues/generated.md): Generated definitions use the named queue infrastructure. Messages remain instances of the original CLR type; Nexus no longer emits message or job subclasses. Configure RoutingQueueName to create an explicit virtual entry point for ShouldEnqueue routing, or enqueue directly into a concrete generated queue by name.
- [Queue message history](https://nexus.commercemind.se/queues/history.md): Nexus can keep track of the history of messages with identity. This means that you get a full audit trail of the content of the messages, when they change and what changed on them.
- [Message identity and IQueueMessageWithId](https://nexus.commercemind.se/queues/identity.md): The IQueueMessage interface doesn't contain any properties so you can define your message in any way you want. But using IQueueMessage means that the system won't have any knowledge of message identity. The system won't compare two messages to see if they are identical to prevent duplicates in a queue.
- [In-memory queues](https://nexus.commercemind.se/queues/in-memory.md): Queues in Nexus are backed by a database but in some cases you want to squeeze the last bit of performance out of your queues and then the overhead of a database can become too much for certain use cases, or if you need to relieve your database of the work needed to handle some very busy queues.
- [Queues overview](https://nexus.commercemind.se/queues.md): Unlike popular message buses and event queues this system uses an SQL database to store messages and also offers in-memory storage.
- [Queue processing jobs](https://nexus.commercemind.se/queues/jobs.md): There's two interfaces for queue processing jobs included in the SDK. One implementation that process messages one by one and one that process messages in batch.
- [Processing directly from Kafka topics](https://nexus.commercemind.se/queues/kafka.md): Nexus allows you to use Kafka as an external pending storage, which means that Nexus reads and processes messages directly from Kafka without first storing them in an SQL backed Nexus queue.
- [Queue maintenance](https://nexus.commercemind.se/queues/maintenance.md): Nexus runs queue maintenance independently from the scheduled-job loop. The job loop therefore does not query every
- [Named queues](https://nexus.commercemind.se/queues/named.md): Named queues let several independently processed queues share a CLR message type. Define the destinations when registering queues:
- [Message priority](https://nexus.commercemind.se/queues/priority.md): The default behavior in Nexus is to process messages in the order that they come in; oldest first. In some cases this is not granular enough and you have some messages that needs to be prioritized over others. Nexus allows you to control this by passing a number as priority when you enqueue the message. Eg:
- [Queue processing settings](https://nexus.commercemind.se/queues/processing-settings.md): Processing implementations supply code defaults. The new Admin UI's Processing tab can save overrides for an individual concrete queue without redeploying the application. Overrides are shared across instances and survive restarts.
- [Distributed queue processors](https://nexus.commercemind.se/queues/processors.md): Distributed queue processors are an opt-in alternative to queue jobs for high-throughput queues. A queue job has one active run across the Nexus cluster. A distributed processor runs a worker pool on every application instance and relies on Nexus's atomic message leases to divide the work safely.
- [Processing directly from RabbitMQ queues](https://nexus.commercemind.se/queues/rabbitmq.md): Nexus allows you to use RabbitMQ as an external pending storage, which means that Nexus reads and processes messages directly from RabbitMQ without first storing them in an SQL backed Nexus queue.
- [Processing directly from Redis](https://nexus.commercemind.se/queues/redis.md): Nexus allows you to use Redis as an external pending storage, which means that Nexus reads and processes messages directly from Redis without first storing them in an SQL backed Nexus queue.
- [Storing processed messages](https://nexus.commercemind.se/queues/retention.md): The default behavior of a Nexus queue is to delete messages when they have been processed. But for some use cases it's interesting to keep the processed messages. You can control how for long processed messages are stored on the [Queue] attribute like this:
- [Retrying queue messages](https://nexus.commercemind.se/queues/retry.md): When you implement a queue processing job you might end up in a situation where you can't process the message right now but you know that you'll soon want to try it again. Such as if you detect that a system that you want to send the message to is down at the moment so you want to try again in X minutes.
- [Queue statistics](https://nexus.commercemind.se/queues/statistics.md): Nexus can store statitics for your queues to help visualize the activity in a queue. If you've enabled statistics you can find them in the Admin UI under Statistics and in the queue list and queue details. The statistics shown in the queues list is the total number of status changes/total activity in a queue.
- [Queue message validation](https://nexus.commercemind.se/queues/validation.md): If you need to validate messages before they're added to Nexus there's two approaches. Either you can let your message class implement IQueueMessageWithValidation like this:
- [Virtual queues](https://nexus.commercemind.se/queues/virtual.md): Depending on your application you might not want the message producer to be in complete control of the message that is added to a queue. And in some cases a single event should cause multiple messages to be added to different queues. But you don't want to force the message producer to have to think about that.
- [Webhooks for Nexus queues](https://nexus.commercemind.se/queues/webhooks.md): Webhooks is a popular way of letting another web application notify your web application that something has happened by posting data to an endpoint in your application. Nexus supports this out-of-the-box by automatically creating an endpoint for each queue in the system that can be used given to another application to send notifications to.
- [Terms of use](https://nexus.commercemind.se/tou.md): Nexus is free-of-charge and licensed under the Apache 2.0 license. It is however not publically available as the repository is private and the NuGet packages are hosted on a private feed.