ProsoGenericTools 1.3.0

C'EST QUOI ProsoGenericTools ?

Cette librairie inclu un générique basé sur la technologie ADO.net.

L'objectif de cette librairie est de factoriser les opérations répétitive, notament le (CRUD) tout en les optimisant et en les exposant implicitement dans toutes les classes qui en ont besoin, par le billet de l'héritage.

INSTALLATION

• Via package Nuget: Rechercher le package ProsomoADOtools et installer la version la plus récente.
• Via la console du gestionnaire de package: Dans la console, executer la commande NuGet\Install-Package ProsomoADOtools, vous pouvez rajouter ensuite '-Version num_version', pour spécifier la version a installer.
• Configuration de la chaine de connection: Dans le point d'entrer de votre application, vous devez passer la chaine de connection a la librairie. Utiliser la propriété ConnectionString statique de l'objet AdoContext: (AdoContext.ConnectionString = chaine_de_connection).

PREREQUIS

En règle génèrale, toute table dans une base de données relationnel, comporte un champ dèidentification unique. Pour le cas de ce systeme, ce champ devra toujours s'appeler (ID).

• Se rassurer que toutes les tables contiennent le champ ID.
• Les champs de type Date dans la BD contenant la valeur ne doivent pas contenir de date vide, soit la valeur '000-00-00 00:00:00', le systeme ne pourra pas les interpretés comme une date valide. Faudra les remplacer a la place par '0001-01-01' ou autre valeur.

MAPPING, COMMENT LE MODELE COMMUNIQUE AVEC LA BASE DE DONNEES ?

→ Pour le bon fonctionnement des méthodes du générique, chaque modèle doit etre concilier avec la DB.

• Les noms de champs en DB doivent être identique aux noms de propriétés dans le programme.
• Certaines propriétés peuvent ne pas être utile pour les requête select, insert ou upate. Utiliser les decorateurs [IgnoreForSelectQuery] pour ignorer une propriété qui ne sera pas utiliser dans les requête Select, [IgnoreForInsertQuery] pour ignorer une propriété qui ne sera utiliser dans les requête insert et [Ignore ForUpdateQuery] pour les requêtes update.
• NB: Dans le code, il est inutile d'ignorer une propriété qui n'est pas présente en BD, car cela se fait automatiquement. Donc ignorer juste les champs qui existent vraiment en BD et dont le mapping n'est pas souhaité pour un type de requête.

FONCTIONNEMENT ET UTILISATION

→ Plusieurs méthodes sont exposé par le générique.

• dInsert / dUpdate: accessible uniquement en protected.
• Update: Si la donnée existe, elle est mise a jour (dUpdate), sinon elle est inserer (dInsert).
• Select / SelectAll: Sélectionne une entité via son Id, ou toute les entités.
• SelectOneWhere / SelectAllWhere: Sélectionne une seul ou plusieurs entité en passant une chaine décrivant le filtre de la clause where, et un paramètre pour la requête (optionnel).
• SearchOne / SearchAll: Sélectionne une seul ou plusieurs entité en passant une chaine décrivant la requête complète de sélection, et un paramètre pour la requête (optionnel).
• SearchAllDynamic: Sélectionne plusieurs données et les retournes dans une liste d'objet dynamique (aucun mapping avec le modèle).
• ExecuteNonQuery: Prend une requête quelquonque en paramètre et l'exécute.
• DeleteWhere: avec un paramètre personnalisé pour la clause where.
• HasAny: vérifie si une donnée existe dans la requête passé en paramètre.

→ Sélection de données provenant de plusieurs table (LES JOINTURES).

• Les méthodes SearchOne et SearchAll possèdent un paramètre (separatorField) qui permet de définir la limite de séparation (nom du champ) pour le mapping du modèle. L'objet est mappé et les champs supplémentaires sont placé dans un objet dynamique ( DynamicData ).

• DynamicData: Est une propriété du générique, qui expose a chaque modèle les propriétés supplémentaire non mappé dans la requete. En considérant cet exemple de requete, EX: SELECT User.*, Role.Name, Role.Type FROM User JOIN Role ON Role.ID = User.RoleID la valeur du parametre separatorField devra etre Name, l'objet User sera mapper, et la proprété DynamicData contiendra un objet avec les champs {Name: value, Type: value}

• Toutes les méthodes de sélection multiple, sont basé sur le principe de lazy loading et renvoi un objet DataResult, contenant la liste de donnée sélectionner, et le total de données existant dans la BD.

• Les méthodes du générique peuvent etre redéfini, a l'exception des methodes statique (Sélection de données) qui doivent etre masqué par le nouveau comportement.

ENVOI DE COURRIELS VIA MICROSOFT GRAPH

→ En plus de l'envoi SMTP classique, la librairie permet d'envoyer un courriel via l'API Microsoft Graph (endpoint sendMail). Le transport est choisi automatiquement par Send / SendAsync selon la configuration : si la classe de configuration implémente IProsoConfigMSGraph et fournit un objet MSGraphSettings, l'envoi passe par Microsoft Graph ; sinon, par SMTP (SmtpSettings.SmtpClient). Aucun autre changement de code n'est requis dans l'application.

• Prérequis Azure: une inscription d'application (App registration) dans Azure AD avec la permission d'application Mail.Send (Microsoft Graph) et le consentement d'un administrateur, ainsi que le certificat public (.cer) téléversé dans l'inscription (authentification par certificat). Pour restreindre les boîtes aux lettres depuis lesquelles l'application peut envoyer, utiliser une Application Access Policy Exchange Online.
• Configuration: dans le point d'entrée de votre application, la classe de configuration passée à ProsoContext.Configure doit implémenter l'interface IProsoConfigMSGraph (qui étend IProsoConfig) et fournir un objet MSGraphSettings : TenantId, ClientId, un moyen d'authentification (voir ci-dessous) et From — l'adresse d'expéditeur par défaut. Les configurations existantes qui n'implémentent que IProsoConfig continuent d'envoyer par SMTP sans changement.
• Authentification, par ordre de priorité :
  • Certificate — un objet X509Certificate2 (avec clé privée) fourni directement ;
  • CertificateThumbprint — l'empreinte du certificat, chargé automatiquement depuis le magasin de certificats Windows « Personnel » (utilisateur courant, puis machine locale) où il doit être installé avec sa clé privée. L'empreinte peut être copiée telle quelle depuis certmgr.msc (les espaces et caractères invisibles sont nettoyés) ;
  • ClientSecret — un secret client Azure AD.
• Utilisation:
  • message.Send(); — envoi selon la configuration (Graph ou SMTP), avec l'expéditeur par défaut.
  • message.Send("expediteur@domaine.com"); — envoi depuis une adresse précise (boîte aux lettres du tenant). En SMTP ce paramètre est ignoré — SMTP ne permet pas de changer l'expéditeur à l'envoi.
  • await message.SendAsync(...); — version asynchrone (Graph ou SMTP).
• Résolution de l'expéditeur (Graph): le paramètre pFromAddress, sinon la propriété From du message, sinon MSGraphSettings.From.
• Comportement debug: DisableSendingEmail et EmailOnDebug se comportent exactement comme avec l'envoi SMTP (redirection de tous les courriels vers EmailOnDebug, CC et BCC retirés).
• Images incorporées: les images inline référencées par cid: (pièces jointes avec disposition inline) sont prises en charge. La méthode Message.EmbedDataUriImages() convertit les images data: du corps HTML en pièces jointes inline, compatibles avec la plupart des clients courriel (Outlook n'affiche pas les data: URIs). Les AlternateViews de System.Net.Mail ne sont pas transposées vers Graph.
• Limites: chaque pièce jointe est limitée à environ 3 Mo (limite fileAttachment de l'API Graph, pas de session de téléversement). Un succès (HTTP 202) signifie que Graph a accepté le courriel, pas qu'il a été livré.
• NB: sur .NET Framework 4.8, le protocole TLS utilisé suit la configuration du système (SystemDefault) — sur un Windows ancien ou mal configuré, il peut être nécessaire d'activer TLS 1.2 au niveau de l'OS.