DOCUMENTATION NTi

Entity Framework Core 8 pour NTi

VUE D'ENSEMBLE

Entity Framework Core pour NTi est un ORM (Object-Relational Mapper), conçu pour exploiter les capacités des bases de données DB2 for i (DB2/400 ou DB2 iSeries) sur IBM i. Il permet aux développeurs .NET de bénéficier d'une interface familière et performante pour interagir avec DB2 for i. Avec EF Core pour NTi, vous pouvez:

  • Exploitez DB2 for i avec des outils modernes .NET, pour développer de nouvelles applications à la vitesse de l'éclair, que vous partiez de zéro (code first) ou d'une base de données existante (DB First).
  • Simplifiez vos développements en interagissant avec vos données via LINQ directement, sans avoir à écrire de SQL.
  • Développer sur plusieurs plateforme (Windows, Linux ou macOS.)

Cette documentation ne couvre pas en détails les concepts généraux d’entity Framework Core, qui sont standardisé. Pour les notions avancées et les bonnes pratiques d’EF Core, consultez la documentation officielle de Microsoft

PRÉREQUIS ET INSTALLATION

PRÉREQUIS

  • .NET SDK 8.
  • Visual Studio 2022 ou équivalent.
  • Une base DB2 for i accessible.

INSTALLATION

Ajoutez le package NuGet Aumerial.EntityFrameworkCore, soit directement en utilisant l’interface de gestion de packages NuGet dans visual Studio, soit via l’interface en ligne de commande de votre éditeur de code.

dotnet add package Aumerial.EntityFrameworkCore

Importez ensuite l’espace de noms pour utiliser EntityFramework Core dans votre projet

using Aumerial.EntityFrameworkCore

💡 Pour les migrations et scaffolding, utilisez uniquement Microsoft.EntityFrameworkCore.Design version 8.0.X pour assurer la compatibilité avec NTi EF Core et .NET 8.

Configuration du DbContext

Créez une classe héritant du DbContext, qui définira les entités et les configurations de votre base.

using Microsoft.EntityFrameworkCore; 

public class AppDbContext : DbContext 
{ 
    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { } 
    
    // Ajoutez vos DbSet ici 
    public DbSet<MyEntity> MyEntities  { get; set; } 
}

Dans un Projet Web, utilisez l'injection de dépendance, et Enregistrer votre DbContext dans le fichier Program.cs

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

builder.Services.AddDbContext(options =>
    options.UseNTi(connectionString));

💡 Pour des tâches asynchrones ou des services en arrière plan, utilisez AddDbContextFactory.

GESTION DES TYPES DE DONNÉES SPÉCIFIQUES

  • Support des types BLOB

Vous pouvez stocker des fichiers ou des images directement dans votre base IBM i en utilisant des colonnes de type BLOB.

[Column(TypeName = "BLOB(1M)"), DataType(DataType.Upload)]
public byte[] ProfilePhoto { get; set; }
  • Configuration Globale des Longueurs

Vous pouvez définir une longueur par défaut pour les types varchar, varbinary, et vargraphic lors de l’enregistrement de votre Dbcontext.

builder.Services.AddDbContextFactory<AppDbContext>(
    options =>
    options.UseNti(connectionString, opt => opt.VarfieldMaxLength(1024, 256, 512)));
  • 1024 : Longueur par défaut pour VARCHAR
  • 256 : Pour VARBINARY
  • 512 : Pour VARGRAPHIC

Vous pouvez également spécifier la longueur directement dans vos entités en utilisant l’attribut [MaxLenght]

[Column(TypeName = "VARCHAR"), MaxLength(128)]
public string Description { get; set; }

Création des Entités et Migrations (Code First)

Lorsque vous travaillez avec NTi EF Core pour créer des tables à partir de zéro, commencez par choisir un schéma pour organiser vos tables, définissez vos entités dans le code et appliquez les migrations.

  • Choisir le Schéma

Ajoutez un schéma par défaut dans votre chaîne de connexion pour garantir que toutes les tables créées seront placées dans ce schéma.

server=myserver;user=myuser;password=mypassword;database=mydb;database=MYSCHEMA;

Si vous avez besoin de placer certaines tables dans des schémas spécifiques, configurez-les explicitement dans le DbContext :

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Product>().ToTable("Product", "MYSCHEMA");
    modelBuilder.Entity<Order>().ToTable("Order", "MYSCHEMA");
}
  • Définir Vos Entités

Créez des classes pour représenter vos tables.

public class Order
{
    public int Id { get; set; }
    public DateTime OrderDate { get; set; }
    public decimal TotalAmount { get; set; }
}

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public List<Order> Orders { get; set; } // Relation avec les commandes
}

Ajoutez ces entités dans votre DbContext :

public DbSet<Order> Orders { get; set; }
public DbSet<Product> Products { get; set; }
  • Générer et Appliquer une Migration

Créer une migration initiale qui génerera Un fichier de migration contenant les instructions SQL nécessaires pour créer les tables définies dans vos entités:

dotnet ef migrations add InitialCreate

Appliquer ensuite la Migration, et mettez à jour la base de données pour appliquer les changements et créer les tables:

dotnet ef database update

Récupération des entités depuis une base existante (DB First)

Pour récupérer le schéma d’une base existante et générer les entités correspondantes, créez une classe DbContext vide:

public class MyDbContext : DbContext { 
    public MyDbContext(DbContextOptions<MyDbContext> options) : base(options) { } 
}

Exécuter ensuite la Commande de Scaffold

dotnet ef dbcontext scaffold "server=myserver;user=myuser;password=mypassword;database=mydb" Aumerial.EntityFrameworkCore --output-dir Data/Models --schema mydb
  • --output -dir: spéficie l’emplacement des entités générés (ex Data/Models).
  • --schema: précise le schema à récupérer (ex myschema)

Si aucune migration n’a encore été créée,générez une migration initiale vide:

dotnet ef migrations add InitialCreate

Vider “up” et “down” dans le fichier généré pour éviter les changements automatiques.

protected override void Up(MigrationBuilder migrationBuilder) 
{ 
// Laissez vide 
} 
protected override void Down(MigrationBuilder migrationBuilder) {
 // Laissez vide
 }

Cela permet d’éviter de supprimer ou recréer accidentellement des tables existantes lors de l'application des migrations.

Créez une classe C# pour représenter la nouvelle table, ou rajoutez ou modifiez une propriété sur une entité existante.

public class MyNewTable { 
public int Id { get; set; } 
public string Name { get; set; } 
public DateTime CreatedAt { get; set; } 
}

Ajoutez cette entité dans le DbContext:

public DbSet<MyNewTables>  MyNewTables { get; set; }

Générez la nouvelle Migration pour cette table:

dotnet ef migrations add AddMyNewTable

Puis mettez à jour la base de données pour inclure la nouvelle table en appliquant la migration.

dotnet ef database update

Génération Automatique des CRUD (entités existantes)

Si vos entités sont déjà définies dans votre projet, vous pouvez générer automatiquement des pages ou des composants CRUD avec les outils intégrés de Visual Studio ou en utilisant Entity Framework Core.

Pour une Application Blazor Server

Création d'un Composant CRUD.

Click droit sur le dossier Pages dans votre projet Blazor Server.

Sélectionnez : Ajouter > Nouvel élément généré automatiquement > Composants Razor avec Entity Framework (CRUD).

Configurer les Options

  • Classe de Modèle : Sélectionnez une entité existante (par exemple, Product).
  • Classe de DbContext : Sélectionnez votre DbContext (par exemple, AppDbContext).

Visual Studio génère automatiquement un ensemble de composants Razor CRUD dans un dossier dédié (par exemple, ProductsPages), avec les fichiers suivants :

  • Index.razor : Liste des enregistrements.
  • Create.razor : Formulaire pour ajouter un nouvel enregistrement.
  • Edit.razor : Formulaire pour modifier un enregistrement existant.
  • Details.razor : Affiche les détails d’un enregistrement.
  • Delete.razor : Confirmation et suppression d’un enregistrement.