# Getting Started

Kista is a framework that provides a set of abstractions and implementations of the [*Repository Pattern*](https://en.wikipedia.org/wiki/Repository_pattern), to simplify the access to data sources in your application while keeping your domain model decoupled from any specific persistence technology.

Below you will find a quick and generic guide to start using the framework in your application.

To learn about the specific usage of the framework, you can read the following documentation:

| Topic                                                                                  | Description                                                                                                                                                   |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [*Using the Entity Framework Core Repository*](/repository-implementations/ef-core.md) | Learn how to use the Repository pattern with [Entity Framework Core](https://github.com/dotnet/efcore)                                                        |
| [*Using the MongoDB Repository*](/repository-implementations/mongodb.md)               | Accessing [MongoDB](https://mongodb.com) databases through the Repository pattern                                                                             |
| [*Using the In-Memory Repository*](/repository-implementations/in-memory.md)           | Interface a volatile and in-process storage using a Repository pattern.                                                                                       |
| [*Filtering*](https://github.com/deveel/kista/blob/main/docs/filtering/README.md)      | Expression-based and Dynamic LINQ filtering with automatic service resolution                                                                                 |
| [*Filter Cache*](/filtering/filter-cache.md)                                           | Bounded expression caching for high-throughput Dynamic LINQ queries                                                                                           |
| [*The Entity Manager*](/entity-manager.md)                                             | Provide your application with a business layer on top of the Repository for additional functions (*logging*, *validation*, *caching*, *event sourcing*, etc.) |
| [*Repository Lifecycle*](/repository-lifecycle.md)                                     | Automate repository creation, teardown, and seeding during application startup                                                                                |
| [*Extending the Repository*](/custom-repository.md)                                    | Learn how to create a custom repository to access your data source, according to your specific data logic                                                     |
| [*Multi-Tenancy*](/multi-tenancy.md)                                                   | Learn how to use the framework in a multi-tenant application                                                                                                  |
| [*User Entities*](/user-entities.md)                                                   | Learn how to define and query entities that are scoped to a specific user                                                                                     |
| [*Sample Application*](/sample-app.md)                                                 | A complete ASP.NET Core reference app with lifecycle management and CRUD endpoints                                                                            |

## Installation

The framework is organized into a *kernel* package (`Kista`) that provides the basic interfaces and abstractions, and a set of *driver* packages that implement those abstractions for specific data sources.

When you install any driver package, the kernel package is automatically pulled in as a transitive dependency — you do not need to install it explicitly.

### Requirements

The library targets the following .NET runtimes:

| .NET Runtime | Supported |
| ------------ | :-------: |
| .NET 8.0     |     ✅     |
| .NET 9.0     |     ✅     |
| .NET 10.0    |     ✅     |

> Support for .NET 6.0 and .NET 7.0 was dropped. Please ensure your project targets .NET 8.0 or later.

### The Kernel Package

All driver packages are built on top of the *kernel* package that provides the core interfaces and abstractions. If you want to develop your own driver for a specific data source, depend only on `Kista` and implement the `IRepository<TEntity>` interface.

```bash
dotnet add package Kista
```

### The Drivers

| Driver                                                                                | Package                             | Description                                                                                                                      |
| ------------------------------------------------------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| [*In-Memory*](/repository-implementations/in-memory.md)                               | `Kista.InMemory`                    | A volatile, in-process repository — ideal for testing and prototyping.                                                           |
| [*MongoDB*](/repository-implementations/mongodb.md)                                   | `Kista.MongoFramework`              | Stores entities in a MongoDB database via [MongoFramework](https://github.com/turnersoftware/mongoframework).                    |
| [*MongoDB Multi-Tenant*](/multi-tenancy.md)                                           | `Kista.MongoFramework.MultiTenant`  | Multi-tenant MongoDB connection management via [Finbuckle.MultiTenant](https://github.com/Finbuckle/Finbuckle.MultiTenant).      |
| [*Entity Framework Core*](/repository-implementations/ef-core.md)                     | `Kista.EntityFramework`             | Stores entities in any relational database supported by [Entity Framework Core](https://github.com/dotnet/efcore).               |
| [*EF Core Multi-Tenant*](/repository-implementations/ef-core.md#multi-tenant-support) | `Kista.EntityFramework.MultiTenant` | Multi-tenant EF Core with database-per-tenant or shared-database strategies.                                                     |
| [*Dynamic LINQ*](/repository-implementations.md#dynamic-linq-support)                 | `Kista.DynamicLinq`                 | Runtime string-based filter expressions via [System.Linq.Dynamic.Core](https://github.com/zzzprojects/System.Linq.Dynamic.Core). |
| [*Entity Manager*](/entity-manager.md)                                                | `Kista.Manager`                     | Business layer with validation, normalization, caching, and event sourcing.                                                      |
| [*Entity Manager EasyCaching*](/entity-manager/caching-entities.md)                   | `Kista.Manager.EasyCaching`         | Second-level caching for EntityManager via [EasyCaching](https://github.com/dotnetcore/EasyCaching).                             |
| [*Entity Manager ASP.NET Core*](/entity-manager/http-request-cancellation.md)         | `Kista.Manager.AspNetCore`          | ASP.NET Core integration for automatic HTTP request cancellation.                                                                |
| [*Entity States*](/index.md)                                                          | `Kista.States.Core`                 | Entity state management abstractions (experimental).                                                                             |

## Instrumentation

The library provides a fluent builder API via `AddRepositoryContext()` to configure repositories, drivers, and cross-cutting concerns in a unified way.

### Using the Fluent Builder

```csharp
// Program.cs

// In-Memory driver
builder.Services.AddRepositoryContext()
    .UseInMemory();

// Entity Framework Core driver
builder.Services.AddRepositoryContext()
    .UseEntityFramework<MyDbContext>(b => b
        .ConfigureDbContext(opts => opts.UseSqlServer("...")));

// MongoDB driver
builder.Services.AddRepositoryContext()
    .UseMongoDB<MyMongoContext>(b => b
        .WithConnectionString("mongodb://..."));
```

Each driver call returns to the parent builder, allowing you to chain multiple concerns:

```csharp
builder.Services.AddRepositoryContext()
    .UseEntityFramework<AppDbContext>(b => b
        .ConfigureDbContext(opts => opts.UseSqlServer("...")))
    .WithManagement()
    .WithEasyCaching();
```

### Assembly Scanning

Use `ScanRepositories()` to automatically discover and register repository types from one or more assemblies:

```csharp
builder.Services.AddRepositoryContext()
    .UseInMemory()
    .ScanRepositories(typeof(MyEntityRepository).Assembly);
```

Open generic repositories are registered as open generics; closed repositories are registered via their service interfaces.

### Legacy Registration

The older `AddRepository<T>` extension method is still available for backward compatibility:

```csharp
builder.Services.AddRepository<InMemoryRepository<MyEntity>>();
```

> **Note:** `AddRepository<T>` is marked `[Obsolete]` but not as an error. It will continue to work. Prefer `AddRepositoryContext()` for new code.

### Consuming the Repository

After registration, the following service types become available in the DI container (availability depends on which interfaces the concrete repository implements):

| Service                           | Description                                                             |
| --------------------------------- | ----------------------------------------------------------------------- |
| `MyCustomRepository`              | The concrete repository implementation.                                 |
| `IRepository<MyEntity>`           | Core CRUD and key-based look-up.                                        |
| `IMyCustomRepository`             | The custom interface (if defined) that extends `IRepository<MyEntity>`. |
| `IQueryableRepository<MyEntity>`  | LINQ-based queries (if implemented).                                    |
| `IPageableRepository<MyEntity>`   | Paginated queries (if implemented).                                     |
| `IFilterableRepository<MyEntity>` | Filter-expression–based queries (if implemented).                       |
| `ITrackingRepository<MyEntity>`   | Change-tracking queries (if implemented).                               |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://kista.deveel.org/index.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.