Introduction à Subsonic

Avant tout, on va ajouter, dans le fichier de configuration (App.Config ou Web.Config), la section de configuration pour Subsonic.

<configuration>
...
    <configSections>
    ...
        <section name="SubSonicService" type="SubSonic.SubSonicSection, SubSonic" 
          allowDefinition="MachineToApplication" restartOnExternalChanges="true" requirePermission="false"/>
    ...
  </configSections>

Ceci est la configuration standard pour la section de configuration de Subsonic. Pour plus d’informations sur requirePermission, restartOnExternalChanges et allowDefinition, je vous renvoie à la MSDN :
Propriétés SectionInformation

On va ensuite ajouter une chaîne de connexion dans notre fichier de configuration. On va utiliser une chaîne de connexion tout ce qu’il y’a de plus standard en .net. Les bases de données que l’on peut utiliser par défaut dans Subsonic sont les suivantes :

• SQL Server ;
• MySql ;
• Oracle ;
• Access (avec un provider spécifique) ;
• SQLite ;
• SQL CE.

Dans l’exemple actuel, on va prendre une chaîne de connexion sur une base de données SQL Server.

<connectionStrings>
  <add name="AdventureWorks" 
   connectionString="Data Source=(local)\sqlexpress;Initial Catalog=AdventureWorks;Integrated Security=True"/>
</connectionStrings>

On va ensuite créer la section SubsonicService, dans laquelle on va déterminer le fournisseur de données par défaut que l’on va utiliser.

<SubSonicService defaultProvider="AdventureWorks">
        <providers>
            <clear/>
            <add name="AdventureWorks" type="SubSonic.SqlDataProvider, SubSonic" 
                    connectionStringName="AdventureWorks" />
        </providers>
    </SubSonicService>

Cette configuration signifie que le fournisseur de données par défaut de Subsonic sera le fournisseur Adventureworks, qui utilise (comme c’est original) la chaîne de connexion AdventureWorks, et que c’est un fournisseur de données SQL Server.

Par défaut, l’espace de nom dans lequel seront générées les classes de Subsonic sera Subsonic. On peut, au niveau de cette partie du fichier de configuration, modifier l’espace de nom, grâce à la propriété generatedNamespace. Ici, on va changer l’espace de nom en AdventureWorks.DB :

<SubSonicService defaultProvider="AdventureWorks">
        <providers>
            <clear/>
            <add name="AdventureWorks" type="SubSonic.SqlDataProvider, SubSonic" generatedNamespace="AdventureWorks.DB"
                    connectionStringName="AdventureWorks" />
        </providers>
    </SubSonicService>

Et… c’est tout pour un projet winform/console.
Pour un projet web, on peut, en plus, ajouter une étape supplémentaire, à savoir l’ajout d’un buildprovider, qui va, au moment de la compilation du site web, générer automatiquement la couche de mapping depuis la base de données. Pour cela, il suffit d’ajouter, d’une part, une section buildProviders dans la section compilation de la section system.web du Web.Config.

    <compilation debug="true" >
      <buildProviders>
        <add extension=".abp" type="SubSonic.BuildProvider, SubSonic"/>
      </buildProviders>
    </compilation>

Il suffit ensuite d’ajouter, dans le répertoire App_Code du site web, un fichier avec une extension .abp (le nom du fichier ou son contenu n’importent pas), et à la première configuration, tout sera généré.

Une fois ces étapes passées, on n’a plus qu’à commencer à travailler.

Savoir tout configurer à la main peut être nécessaire, mais vu que des outils existent pour faire le travail à notre place, autant les utiliser.

SubStage est une interface graphique permettant de configurer Subsonic de façon visuelle, ainsi que d’éditer les données, d’accéder à la documentation de l’API, au forum dédié à Subsonic, et aux Work Items en cours sur le projet.

On va refaire plus ou moins les manipulations que l’on vient de faire en manuel. Pour cela, on va commencer par créer une chaîne de connexion, en faisant un clic sur « New Connection String »

On va ensuite configurer notre chaîne de connexion, tout comme on l’a fait dans notre fichier de configuration.

On va ensuite créer un nouveau projet, en cliquant sur « new project », et nommer notre projet (dans mon cas, toujours AdventureWorks)

Enfin, on va configurer le fournisseur de données.
Pour cela, on va sélectionner le projet, puis cliquer sur « new provider ». Par défaut, le fournisseur sélectionné est SQL Server, ce qui me convient tout à fait. Cet écran va me permettre de gérer de nombreuses choses, comme le namespace dans lequel se trouvera le code généré, le lazy load, la possibilité de sélectionner quelles tables et procédures stockées on veut inclure, et cætera.

Une fois que notre configuration nous convient, il ne reste plus qu’à copier, depuis l’onglet « Configuration Output », la configuration qu’on n’aura plus qu’à coller dans le fichier de configuration.

Maintenant que l’on a créé (deux fois) notre fichier de configuration, on en est…toujours au même point (sauf si on travaille sur un site web, auquel cas, tout marche déjà).

On va maintenant générer notre couche d’accès aux données. Pour cela, il faut lancer un exécutable, nommé sonic.exe, et situé dans le répertoire d’installation de Subsonic, dans le sous-répertoire SubCommander.

Donc, dans mon cas, C:\Program Files\SubSonic\SubSonic 2.1 Final\SubCommander\sonic.exe

Comme je suis fainéant, et que le but est de générer le code régulièrement, je vais ajouter, dans les événements de compilation de mon projet, une condition de précompilation qui va générer le code à chaque fois que je compile mon projet.
Pour cela, je vais ajouter un fichier GenererSubsonicDAL.bat dans le répertoire de mon projet, dans lequel je vais ajouter le texte suivant :

C:\Program Files\SubSonic\SubSonic 2.1 Final\SubCommander\sonic.exe generate /out Generated

Et dans les propriétés de mon projet, dans la rubrique « Build Events », et je vais ajouter comme ligne de commande de pré compilation :

Ainsi, à chaque compilation, mon code est régénéré, et je bénéficie d’une vérification à la compilation de mon code.

Une autre option est possible, à savoir ajouter une référence à Subsonic comme outil externe à Visual Studio. Pour cela, il suffit d’aller dans « Outils »/« Outils Externes », puis de cliquer sur ajouter, de renseigner le nom de la commande, l’exécutable à lancer (dans ce cas, sonic.exe), les arguments adéquats (generate /out Generated), et le répertoire initial (ici, on va entrer $(ProjectDir) pour utiliser le répertoire du projet courant).

Une fois configuré, on doit obtenir l’écran suivant (mon Visual Studio est en anglais, désolé…) :

Et on peut accéder à la nouvelle commande dans Outils/SubsonicDAL.

Récupération d’un seul objet▲

  Product objProduct = Product.FetchById(1);

  ProductController controller = new ProductController();
  Product objProduct = controller.FetchByID(1);

            Product objProduct = new Product(712);
            Product objProduct = new Product(Product.Columns.Name, "AWC Logo Cap");

Récupération d’un ensemble d’objets▲

ProductCollection products = new ProductCollection().Load();
ProductCollection products = new ProductController().FetchAll().

     ProductCollection products = new ProductCollection()
         .Where(Product.Columns.Color, "red")
         .Load();

     ProductCollection products = new ProductCollection()
            .Where(Product.Columns.Color, "red")
            .OrderByAsc(Product.Columns.Name)
            . Load ();

     ProductCollection products = new ProductCollection()
            .Load()
            .Where(Product.Columns.Color, "red")
            .OrderByAsc(Product.Columns.Name);

Ajouter un nouvel objet dans la base de données se fait de façon très intuitive. Comme mentionné précédemment, on a deux moyens différents pour insérer des objets. Le premier est d’utiliser la classe représentant la table en question. Pour cela, on va faire :

    objProduct.Save();

La seconde option est d’utiliser le contrôleur de la classe. En effet, le contrôleur nous fournit le moyen d’insérer directement l’objet dans la base, en lui passant l’intégralité des données à insérer.

     new ProductController().Insert(namespace, ProductNumber...

Dans les deux cas, le code appelé sera sensiblement le même, le code de la méthode Save de ProductController appelant le Save de Product.

public void Insert(string Name,string ProductNumber,string Color,
      decimal StandardCost,decimal ListPrice,string Size,decimal? Weight,
      int? ProductCategoryID,int? ProductModelID,DateTime SellStartDate,
      DateTime? SellEndDate,DateTime? DiscontinuedDate,byte[] ThumbNailPhoto,
      string ThumbnailPhotoFileName,Guid Rowguid,DateTime ModifiedDate){
            Product item = new Product();            
            item.Name = Name;            
            item.ProductNumber = ProductNumber;            
            item.Color = Color;            
            item.StandardCost = StandardCost;            
            item.ListPrice = ListPrice;            
            item.Size = Size;            
            item.Weight = Weight;            
            item.ProductCategoryID = ProductCategoryID;            
            item.ProductModelID = ProductModelID;            
            item.SellStartDate = SellStartDate;            
            item.SellEndDate = SellEndDate;            
            item.DiscontinuedDate = DiscontinuedDate;            
            item.ThumbNailPhoto = ThumbNailPhoto;
            item.ThumbnailPhotoFileName = ThumbnailPhotoFileName;            
            item.Rowguid = Rowguid;            
            item.ModifiedDate = ModifiedDate;                    
            item.Save(UserName);
        }

Mettre à jour un objet se fait de la même façon pour la classe Product. La classe ProductController va, elle, exposer une méthode Update. Cette méthode Update est identique à 80 % à la méthode Insert, elle contient en fait seulement deux lignes supplémentaires, à savoir :

    item.MarkOld();
    item.IsLoaded = true;

La raison en est que, lorsque l’on appelle Save (Save étant une méthode de la classe ActiveRecord<T>, qui fait partie du Framework Subsonic), les propriétés IsDirty et IsNew sont testées, permettant de savoir, au moment de l’appel à Save, si on veut faire un insert ou un update.

Les méthodes de sauvegardes proposent des surcharges assez sympathiques. En effet, on peut décider de passer l’utilisateur responsable de la sauvegarde à la fonction Save, en faisant, par exemple, ceci :

    objProduct.Save("pvialatte");

Subsonic propose comme convention que, si une colonne CREATED BY ou MODIFIED BY existe, la chaîne de caractères, l’entier ou le GUID passé à la fonction Save renseigne cette colonne. Évidemment, le comportement est différent pour une mise à jour, qui ne mettra à jour que MODIFIED_BY.

De la même manière, si une colonne CREATED_ON ou MODIFIED_ON existe, on va modifier cette colonne automatiquement, à la sauvegarde ou à la mise à jour d’un Produit…

Tout comme la sauvegarde, la suppression d’un objet en base est simplissime. Pour cela, on va appeler la méthode Delete du contrôleur de produits.

   new ProductController().Delete(712);

On pourra aussi, appeler la méthode Delete statique de l’objet Product. On peut soit supprimer un objet par son Id, soit par une autre valeur unique.

   Product.Delete(712);
   Product.Delete(Product.Columns.Name, "AWC Logo Cap");

Une fois de plus, une convention spécifique de Subsonic existe au niveau de la suppression. En effet, si une colonne DELETED ou IS_DELETED (de type booléen ou bit) existe, on ne va pas supprimer l’enregistrement de la base, mais simplement modifier la valeur de la colonne de suppression de façon à ce qu’elle soit représentée comme supprimée. Attention, c’est une convention, les requêtes de sélection ne se limitent pas, elles aux éléments dont cette valeur est fausse…
Bien entendu, si ces colonnes n’existent pas, on efface les enregistrements…

Pour être sûr de supprimer définitivement les enregistrements, on peut utiliser la méthode Destroy, qui s’appelle exclusivement à partir des objets :

   Product.Destroy(712);
   Product.Destroy(Product.Columns.Name, "AWC Logo Cap");

Les collections permettent aussi de supprimer un ensemble d’objets. Pour cela, il faut préalablement charger une liste d’objets, et marquer les objets que l’on veut supprimer dans cette liste. Ceci se fait en utilisant, au choix, BatchDelete ou SaveAll, après avoir supprimé les éléments que l’on voulait supprimer.

     ProductCollection products = new ProductCollection()
            .Load()
            .Where(Product.Columns.Color, "red")
            .OrderByAsc(Product.Columns.Name);
      while(products.Count > 0){
                products.RemoveAt(0); // RemoveItem() gets called
      }

      products.SaveAll(); // supprime tous les objets, et sauvegarde les modifications
      products.BatchDelete(); // supprime tous les objets dans une transaction, ne sauve pas les autres objets

Le but des requêtes de sélection de Subsonic est d’être le plus proche possible syntaxiquement d’une requête SQL. L’API de Subsonic est en effet conçue sur le mode « fluent interface », ce qui permet de chaîner les contraintes.

La syntaxe de base sera donc de la forme :

    DB.Select("Champ1","Champ2","Champ3").
        From("Table").
        Where("Champ1").
        IsEqualTo(1).
        And("Champ2").
        IsEqualTo(2);

La fonction DB.Select renverra un objet de type SqlQuery. Cet objet de type query expose les méthodes suivantes :

• GetRecordCount : renvoie le nombre d’enregistrements correspondant dans la base de données ;
• Execute : équivaut à ExecuteNonQuery, renverra le nombre d’enregistrements modifiés ;
• ExecuteScalar : équivaut à ExecuteScalar, renvoie le premier élément retourné, sous forme d’objet ;
• ExecuteScalar<T> : équivaut à ExecuteScalar, renvoie le premier élément retourné, sous forme de T ;
• ExecuteReader : équivaut à ExecuteReader, renvoie un Idatareader ;
• ExecuteDataSet : renvoie le résultat de la requête sous forme de DataSet ;
• ExecuteSingle<T> : renvoie la première ligne du résultat, en le convertissant en objet de type T ;
• ExecuteAsCollection<T> : renvoie le résultat de la requête, sous forme d’une collection de T ;
• ToString : renvoie la requête SQL qui va être exécutée.

Pour que ce soit plus parlant, voici une liste de requêtes, récupérées dans les tests unitaires de la solution de Subsonic.

On peut donc exécuter les requêtes avec des chaines :

int records = new DB.Select("productID").
                 From("Products").GetRecordCount();

La même, avec des colonnes typées :

int records = new DB.Select(Product.ProductIDColumn).
                From<Product>().GetRecordCount();

ou encore :

            int records = new DB.Select(Product.Columns.ProductID).
                From<Product>().GetRecordCount();

Pour récupérer un objet, on va faire :

Product p = new DB.Select().From<Product>().
               Where("ProductID").IsEqualTo(1).ExecuteSingle<Product>();

ou même :

            Product p = new Select().From<Product>().
               Where(Product.Columns.ProductID).
               IsEqualTo(1).ExecuteSingle<Product>();

Si on veut récupérer une collection, on va faire :

   ProductCollection products = DB.Select().From<Product>()
                    .Where(Product.Columns.Category).IsEqualTo(5)
                    .And(Product.Columns.ProductID).IsGreaterThan(50)
                    .ExecuteAsCollection<ProductCollection>();

Et, pour une jointure, on va faire :

CustomerCollection customersByCategory = new Select()
    .From<Customer>()
    .InnerJoin<Order>()
    .InnerJoin(OrderDetail.OrderIDColumn, Order.OrderIDColumn)
    .InnerJoin(Product.ProductIDColumn, OrderDetail.ProductIDColumn)
    .Where("CategoryID").IsEqualTo(5)
    .ExecuteAsCollection<CustomerCollection>();

De la même façon que pour les requêtes de sélection, Subsonic expose des interfaces permettant des requêtes d’insertion, de suppression, et de mises à jour assez puissantes.

Elles prendront la forme suivante :

new Insert().Into<Region>().Values("test1").Execute();
new Update<Region>().Set("UnitPrice").EqualTo("test2").Where("regiondescription").IsEqualTo("test1").Execute()
new Delete().From(<Region>().Where("regiondescription").Like("test%").Execute();

Une fois de plus, on retrouve une pseudosyntaxe SQL, à laquelle on s’habitue très vite.

Pour finir avec les requêtes, on va voir les possibilités de transactions de Subsonic.

Subsonic propose deux méthodes différentes pour profiter du mécanisme de transactions. La première est de générer un ensemble de requêtes, et de les passer à la fonction ExecuteTransaction de SubSonic.SqlQuery :

            List<Insert> queries = new List<Insert>();
            queries.Add(new Insert().Into(Region.Schema).Values("test1"));
            queries.Add(new Insert().Into(Region.Schema).Values("test2"));

            SubSonic.SqlQuery.ExecuteTransaction(queries);

La seconde est de créer un nouveau scope de transaction, et d’exécuter toutes nos requêtes dans ce scope.

  using(TransactionScope scope = new TransactionScope()){
                new Insert().Into(Region.Schema).Values("test1");
                new Insert().Into(Region.Schema).Values("test2");
                new Insert().Into(Region.Schema).Values("test3");
  }

Dans les deux cas, Subsonic fera automatiquement le commit final, et un rollback en cas d’erreur.