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:

• Exploiter DB2 for i avec des outils modernes .NET, pour développer de nouvelles applications en un temps record, que vous partiez de zéro (code first) ou d'une base de données existante (DB First).
• Simplifier 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 [MaxLength]

[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=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énèrera 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écifie 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.

Si vos entités sont déjà définies dans votre projet, Visual Studio peut générer automatiquement des composants Razor CRUD en quelques clics.

1. Faites un clic droit sur le dossier Pages de votre projet Blazor Server
2. Sélectionnez Ajouter > Nouvel élément généré automatiquement > Composants Razor avec Entity Framework (CRUD)
3. Configurez les options :
   • Classe de Modèle : sélectionnez une entité existante (ex. Product)
   • Classe de DbContext : sélectionnez votre DbContext (ex. AppDbContext)

Visual Studio génère automatiquement un ensemble de composants Razor CRUD dans un dossier dédié (ex. ProductsPages) :

• Index.razor - liste des enregistrements
• Create.razor - formulaire d'ajout
• Edit.razor - formulaire de modification
• Details.razor - affichage du détail d'un enregistrement
• Delete.razor - confirmation et suppression

Et maintenant ?

• CRUD avec EF Core 8 - exemple complet avec Entity Framework Core sur DB2 for i
• Connexion - chaîne de connexion, pool, MFA
• Guide de démarrage rapide - première connexion et premiers appels IBM i