# Installation

BackWave is a library you add to an existing .NET application. This page covers
the packages, what each one is for, and how to select storage. For an end-to-end
walkthrough that gets a job running, start with the
[Quickstart](/docs/introduction/quickstart).

## Prerequisites

- **.NET**: a supported modern .NET SDK and runtime.
- **A database**. BackWave stores its queue in a database you already run via a
  **Storage Adapter**, so there is no broker to provision, secure, and monitor.
  SQLite counts here: it needs a file path and no server. The In-Memory Store
  needs no database at all, but it persists nothing, so it is for tests and
  local development.

## Packages

Add the core package plus the host integration. Storage Adapters and the
Dashboard are separate packages you add as needed.

```bash title="Terminal"
# Core + host integration, always needed
dotnet add package BackWave
dotnet add package BackWave.Hosting

# Add a Storage Adapter for durable storage
dotnet add package BackWave.Postgres     # Postgres
dotnet add package BackWave.SqlServer    # SQL Server
dotnet add package BackWave.Sqlite       # SQLite (embedded, single-host)

# Optional: the operations dashboard
dotnet add package BackWave.Dashboard

# Optional: job traces and metrics on your OpenTelemetry provider
dotnet add package BackWave.OpenTelemetry

# Optional: ride your EF Core transaction for Transactional Enqueue
dotnet add package BackWave.EntityFrameworkCore
```

| Package | What it gives you |
| --- | --- |
| [`BackWave`](https://www.nuget.org/packages/BackWave) | The Core, the `[Job]` model, the source generator, and the In-Memory Store. |
| [`BackWave.Hosting`](https://www.nuget.org/packages/BackWave.Hosting) | Wires Worker Groups into the generic host as hosted services. |
| [`BackWave.Postgres`](https://www.nuget.org/packages/BackWave.Postgres) | The Postgres Storage Adapter (`PostgresJobStore`). |
| [`BackWave.SqlServer`](https://www.nuget.org/packages/BackWave.SqlServer) | The SQL Server Storage Adapter (`SqlServerJobStore`). |
| [`BackWave.Sqlite`](https://www.nuget.org/packages/BackWave.Sqlite) | The embedded, single-host SQLite Storage Adapter (`SqliteJobStore`). |
| [`BackWave.Dashboard`](https://www.nuget.org/packages/BackWave.Dashboard) | The middleware-hosted operations Dashboard and its Operator Actions. |
| [`BackWave.OpenTelemetry`](https://www.nuget.org/packages/BackWave.OpenTelemetry) | One call that registers the job traces and metrics on your OpenTelemetry provider. |
| [`BackWave.EntityFrameworkCore`](https://www.nuget.org/packages/BackWave.EntityFrameworkCore) | EF Core integration so an enqueue can ride your own transaction. |

The source generator ships inside `BackWave`. There's no separate analyzer
package and no `Generator` reference to wire up. It emits a payload record, an
`IJobHandler<T>`, the wire format, and `BackWave.Generated.BackWaveJobs.Module`
from your `[Job]` methods.

> **The plain path is the default, and it's reflection-free.** `BackWave`,
> `BackWave.Hosting`, and `BackWave.Postgres` do payload serialization and
> handler dispatch through generated code, with raw ADO in the Postgres adapter
> and no EF anywhere. That full enqueue→execute→store→observe loop - core,
> hosting, Postgres, and OpenTelemetry alongside - publishes warning-clean under
> Native AOT. `BackWave.EntityFrameworkCore` is an optional leaf you add only for
> [Transactional Enqueue](/docs/guides/transactional-enqueue-with-ef-core)
> through a `DbContext`, and it's the one package to keep out of an AOT worker.
> See [Publish with Native AOT](/docs/guides/publish-with-native-aot).

## Reading and building the source

Every package is built from the [public BackWave
repository](https://github.com/Back-Wave/BackWave), which holds one directory per
package under `src/`, named for the package itself. Clone it and run
`dotnet build` when you want to read the engine, debug against a local build, or
run the tests. The source is available under the [PolyForm Shield
License](/licensing/backwave-license) for the base packages and the [commercial
license](/licensing/pro-license) for Pro, which permit reading, building, and
modifying, but not shipping a competing product.

You rarely need a local build to look inside. Each published package carries
Source Link and ships its symbols as a separate `.snupkg`, so with symbol lookup
enabled your debugger steps from your own code straight into the BackWave source
for the exact commit that package was built from.

## Choosing storage

BackWave implements one **Storage Contract**; the implementation you select
decides durability and deployment shape. Pick by what your deployment needs, not
by environment. Postgres is just as valid on your laptop, and SQLite is a fine
fit for a simple single-host service.

- **In-Memory Store**: `BackWave.Storage.InMemory.InMemoryJobStore`. A
  first-class implementation that needs no database. It isn't durable (jobs
  live in process memory and are lost on restart) and it's single-process, so
  it can't be shared across nodes. Without durability it can't carry the
  [execution guarantee](/docs/core-concepts/execution-guarantee), so its home is
  tests and local dev. It is also the deterministic store that drives Virtual
  Time in tests. If zero infrastructure is what draws you to it, SQLite gives
  you the same thing plus durability, for a file path.
- **Networked Adapter**: `PostgresJobStore` / `SqlServerJobStore`. Durable
  Storage Adapters over a database server reachable across hosts, so a cluster
  of nodes can span machines.
- **Embedded Adapter**: a SQLite-backed adapter (durable, single-host). When
  BackWave's tables live in your own application database file, business writes
  and job enqueues commit in one file and one transaction, the tightest
  **Transactional Enqueue** there is.

Wiring the In-Memory Store:

```csharp title="Program.cs" {5}
using BackWave.Storage.InMemory;

builder.Services.AddBackWave(backwave =>
{
    backwave.UseStore(_ => new InMemoryJobStore());
    // ... UseJobs + AddWorkerGroup
});
```

Wiring a Networked Adapter (Postgres):

```csharp title="Program.cs" {6-10}
using BackWave;
using BackWave.Postgres;

builder.Services.AddBackWave(backwave =>
{
    backwave.UseStore(_ => new PostgresJobStore(new PostgresStoreOptions
    {
        ConnectionString = connectionString,
        AutoMigrate = true, // embedded schema self-applies on startup
    }));
    // ... UseJobs + AddWorkerGroup
});
```

With `AutoMigrate = true` the adapter's embedded schema self-applies on startup,
so there is no manual migration step. Switching to SQL Server is the same shape
with `SqlServerJobStore` and `SqlServerStoreOptions`.

## Verify the install

The fastest sanity check is to wire the In-Memory Store, declare a single
`[Job]`, enqueue it, and confirm the handler runs. That's exactly the
[Quickstart](/docs/introduction/quickstart) flow. From there, see
[Configuration](/docs/introduction/configuration) to tune Worker Groups,
retries, leases, and Concurrency Limits.