AssistantEntities 1.1.47

AssistantEntities

AssistantEntities is a .NET 8.0 shared library designed to centralize database entities and migrations across various backend projects within the Assistant ecosystem. It uses Entity Framework Core with PostgreSQL to provide a unified data model.

Overview

• Centralized Entity Definition: All database models are defined in one place to ensure consistency.
• Migration Management: Handles database schema versions using EF Core Migrations.
• PostgreSQL Integration: Optimized for PostgreSQL using the Npgsql provider.
• Multitenancy Support: Base entities and configurations designed for multitenant architectures.

Requirements

• Runtime: .NET 8.0 SDK or later.
• Database: PostgreSQL.
• Tools: EF Core CLI tools (for running migrations).
  • tools installation command:

    dotnet tool install --global dotnet-ef --version 8.*
  

Setup & Run Commands

Installation

Clone the repository and build the project:

dotnet build

Database Configuration

The library uses a DataContextFactory to resolve the connection string in the following order:

1. Environment Variable: EFCORE_CONNECTION_STRING
2. CLI Argument: Passed directly to the tool after the -- separator (e.g., dotnet ef database update -- "Host=myhost;...")
3. appsettings.json: Reads from ConnectionStrings:DefaultConnection.

If no connection string is found, it defaults to a placeholder for migration generation purposes.

Inline Connection String Examples

If you don't have an environment variable or appsettings.json configured, you can pass the connection string inline:

For Core/Main:

dotnet ef database update --context MainDataContext -- "Host=mio_host;Database=mio_db;Username=mio_utente;Password=mia_password"

For CRM:

dotnet ef database update --context CrmDataContext -- "Host=mio_host;Database=mio_db;Username=mio_utente;Password=mia_password"

For Ada:

dotnet ef database update --context AdaDataContext -- "Host=mio_host;Database=mio_db;Username=mio_utente;Password=mia_password"

Applying Migrations

To apply migrations to a target database, ensure your connection string is set and run:

For Core/Main Migrations:

dotnet ef database update --context MainDataContext

For CRM Migrations:

dotnet ef database update --context CrmDataContext

For Ada Migrations:

dotnet ef database update --context AdaDataContext

Scripts & Common Commands

• Build: dotnet build
• Clean: dotnet clean
• Create Migration (Main): dotnet ef migrations add <Name> --context MainDataContext --output-dir Migrations/Main
• Create Migration (CRM): dotnet ef migrations add <Name> --context CrmDataContext --output-dir Migrations/Crm
• Create Migration (Ada): dotnet ef migrations add <Name> --context AdaDataContext --output-dir Migrations/Ada
• Remove Last Migration (Main): dotnet ef migrations remove --context MainDataContext
• Remove Last Migration (CRM): dotnet ef migrations remove --context CrmDataContext
• Remove Last Migration (Ada): dotnet ef migrations remove --context AdaDataContext
• Update Database (Main): dotnet ef database update --context MainDataContext
• Update Database (CRM): dotnet ef database update --context CrmDataContext
• Update Database (Ada): dotnet ef database update --context AdaDataContext
• Run Tests: dotnet test (Note: Tests should be located in a separate project as per guidelines).

Usage in Projects

When using this package in your projects, you should apply migrations for both contexts at startup. Here is an example of how to do it in your Program.cs or during application initialization:

using (IServiceScope scope = app.Services.CreateScope())
{
    var serviceProvider = scope.ServiceProvider;

    // 1. Apply old migrations (Table __EFMigrationsHistory)
    var dataContext = serviceProvider.GetRequiredService<AssistantEntities.DbContext.DataContext>();
    dataContext.Database.Migrate();
    
    // 2. Apply Main/Core migrations (Table __EFMigrationsHistory_Main)
    var mainContext = serviceProvider.GetRequiredService<AssistantEntities.DbContext.MainDataContext>();
    mainContext.Database.Migrate();

    // 3. Apply CRM migrations (Table __EFMigrationsHistory_Crm)
    var crmContext = serviceProvider.GetRequiredService<AssistantEntities.DbContext.CrmDataContext>();
    crmContext.Database.Migrate();

    // 4. Apply Ada migrations (Table __EFMigrationsHistory_Ada)
    var adaContext = serviceProvider.GetRequiredService<AssistantEntities.DbContext.AdaDataContext>();
    adaContext.Database.Migrate();

    // 5. Optional: Business logic using the unified DataContext
    var checkEnhancerBackground = dataContext.EnhancerBackground.FirstOrDefault();
    if (checkEnhancerBackground != null && (checkEnhancerBackground.IsWorking || checkEnhancerBackground.IsWorkingSendOutcomesOneExpress || checkEnhancerBackground.IsWorkingOcrAcquisition))
    {
        checkEnhancerBackground.IsWorking = false;
        checkEnhancerBackground.IsWorkingSendOutcomesOneExpress = false;
        checkEnhancerBackground.IsWorkingOcrAcquisition = false;
        dataContext.Update(checkEnhancerBackground);
        dataContext.SaveChanges();
    }
}

Dependency Injection Registration

Ensure all contexts are registered in your Program.cs:

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");

builder.Services.AddDbContext<DataContext>(options =>
    options.UseNpgsql(connectionString));

builder.Services.AddDbContext<MainDataContext>(options =>
    options.UseNpgsql(connectionString), x => x.MigrationsHistoryTable("__EFMigrationsHistory_Main"));

builder.Services.AddDbContext<CrmDataContext>(options =>
    options.UseNpgsql(connectionString, x => x.MigrationsHistoryTable("__EFMigrationsHistory_Crm")));

builder.Services.AddDbContext<AdaDataContext>(options =>
    options.UseNpgsql(connectionString, x => x.MigrationsHistoryTable("__EFMigrationsHistory_Ada")));

Environment Variables

Project Structure

• Configurations/: Contains Fluent API configurations for entity mappings (e.g., CRM, Integrations).
• DbContext/: Includes DataContext and DataContextFactory.
• Entities/: Domain models organized by module (Crm, Integrations, Enums).
• Extensions/: Helper methods and extensions.
• Migrations/: EF Core migration files and snapshots.
• GlobalUsings.cs: Project-wide using directives.

Testing

The project uses xUnit for testing. To keep the production library clean, tests are maintained in a separate project (e.g., AssistantEntities.Tests).

• Unit Tests: Use UseInMemoryDatabase for tests that don't require specific PostgreSQL features.
• Integration Tests: Use a real PostgreSQL instance (can be configured via EFCORE_CONNECTION_STRING).

Example of a simple test:

var options = new DbContextOptionsBuilder<DataContext>()
    .UseInMemoryDatabase(databaseName: "TestDb")
    .Options;
using var context = new DataContext(options);
// Perform actions and assertions

License

This library is distributed under the Assistant Proprietary License. SPDX-License-Identifier: LicenseRef-Assistant-Proprietary

See license.txt for more details.

TODO: Add more detailed documentation for specific CRM and Integration entities.