Ce fichier va contenir toutes les caractéristiques et implémentations propres à la classe en elle-même.

Parmi ces éléments, nous trouverons entre autres :

• la gestion des erreurs côté serveur ;
• le log éventuel des opérations ;
• les attributs qui précisent le comportement du « DomainService » ;
• etc.

1. Dans l'arborescence, faites un clic droit (menu contextuel) à l'endroit où vous désirez créer le service, Add - New Item
   
   
2. Sélectionnez « Domain Service Class », saisissez un nom de fichier (Referenciel.cs) et validez !
   
3. Dans cet écran,
   
   
   vérifiez que :
    - le nom de la classe est « Referentiel » ;
    - la propriété « Enable client access » est sélectionnée ;
    - le modèle de données sur lequel se base le service est le bon (ici NorthwindEntities).
       P.-S. S'il n'apparaît pas, c'est que vous avez probablement omis de compiler le projet après la création du modèle EF !
    - aucune entité particulière n'est sélectionnée (en effet, nous créons le fichier principal de notre Référentiel).
   
   Et validez !
   
4. Le résultat est :
   
5. Dans le fichier de code, n'oubliez pas d'ajouter le mot clé partial à la déclaration de la classe,
        public class Referentiel : LinqToEntities… => public partial class Referentiel : LinqToEntities…
   

Le fichier de code ressemble alors à ceci :

namespace NorthWindRIA.Web.Metier.Services
{
    using System.Web.DomainServices.Providers;
    using System.Web.Ria;
    using NorthWindRIA.Web.Metier;
        
    // [RequiresAuthentication] => Attribut qui décommenté, entraine la nécessité d’être authentifié (au sens ASP.net) pour attaquer le service,
    /// <summary>
    /// Classe de base du Referentiel.
    /// </summary>
    [EnableClientAccess()] // Indique que le service est accessible !
    public partial class Referentiel : LinqToEntitiesDomainService<NorthwindEntities>
    {
        // contient ce qui est commun à toutes les déclarations partielles : attributs, etc.
    }
}

Concernant les attributs de classe ci-dessus :

• [RequiresAuthentication()]
  Indique que l'utilisateur doit être authentifié (au sens ASP.net du terme) pour utiliser le service (si décommenté) ;
  
• [EnableClientAccess()]
  Indique que le service est disponible depuis un client.
  

Le fichier RefCustomer.cs (au même titre que RefOrders.cs, RefOrder_Details.cs et RefProducts.cs) va contenir une partie de la classe Referentiel (suivant le principe de classes partielles). Ce fichier va englober toutes les méthodes, queries qui concernent la gestion des Customers (clients).

Pour créer cet élément, voici les opérations.

1. Comme pour le fichier Referentiel.cs,
   faites un clic droit à l'endroit où vous désirez créer le service, Add - New Item,
   
2. Sélectionnez « Domain Service Class » comme type
   
   et entrez « RefCustomer.cs » comme nom de fichier. 
   Puis validez !
   
3. Suit alors l'écran qui définit ce que contient le fichier :
   
   Attention, c'est ici que les choses peuvent sembler étranges.
   
   -> Entrez « Referentiel » comme Domain service class name (même nom que pour le fichier Referentiel.cs).
   -> Sélectionnez EnableClientAccess, ainsi que l'entité « Customers ».
   -> Pour permettre à une application cliente d'effectuer des insertions et modifications sur les objets Customers, n'oubliez pas de sélectionner « Enable Editing ».
   
   Last but not least, sélectionnez « Generate associated classes for metadata ».
   Cette option (importante) demande à Visual de générer une classe de métadonnées nous permettant de fixer les règles de validation par membre (entre autres) de la classe Customer, nous y reviendrons par la suite.
   
4. Ajoutez le mot clé partial dans la déclaration de la classe,
        public class Referentiel : LinqToEntities… => public partial class Referentiel : LinqToEntities…
   
5. Supprimez tout attribut décorant la classe.
   

Le fichier de code donne alors ceci :

namespace NorthWindRIA.Web.Metier.Services
{
    using System.Data;
    using System.Linq;
    using System.Web.DomainServices.Providers;
    using NorthWindRIA.Web.Metier;


    // Classe partielle Referentiel (cf. Referentiel.cs pour les informations de la classe)
    // ce fichier contient la description des services dispo pour les entités Customers
    public partial class Referentiel : LinqToEntitiesDomainService<NorthwindEntities>
    {
        /// <summary>
        /// Retourne la Query de base utilisée lorsqu'un client effectue une requête de sélection
        /// </summary>
        /// <returns>Query sur les entités <see cref="Customers"/> servant de base à toutes les requêtes de sélection provenant des app clientes.</returns>
        public IQueryable<Customers> GetCustomers()
        {
            return this.ObjectContext.Customers;
        }

        /// <summary>
        /// Effectue une insertion (si absent, la tentative d'insertion d'une entité entraine une exception => car interdit)
        /// </summary>
        /// <param name="customers">Client à insérer</param>
        public void InsertCustomers(Customers customers)
        {
            this.ObjectContext.AddToCustomers(customers);
        }

        /// <summary>
        /// Effectue une modification (si absent, la tentative de mise à jour d'une entité entraine une exception => car interdit)
        /// </summary>
        /// <param name="customers">Client à modifier</param>
        public void UpdateCustomers(Customers currentCustomers)
        {
            if ((currentCustomers.EntityState == EntityState.Detached))
            {
                this.ObjectContext.AttachAsModified(currentCustomers, this.ChangeSet.GetOriginal(currentCustomers));
            }
        }

        /// <summary>
        /// Effectue une suppression (si absent, la tentative de suppression d'une entité entraine une exception => car interdit)
        /// </summary>
        /// <param name="customers">Client à supprimer</param>
        public void DeleteCustomers(Customers customers)
        {
            if ((customers.EntityState == EntityState.Detached))
            {
                this.ObjectContext.Attach(customers);
            }
            this.ObjectContext.DeleteObject(customers);
        }
    }
}

III-A-2-a. Le fichier de métadonnées▲

Lorsque l'on génère une classe « Domain Service » basée sur une entité (Customers ici) et que l'option « Generate associated classes for metadata » est sélectionnée,
Visual Studio génère (côté serveur) un fichier qui porte le même nom que le fichier créé, surfixé .metadata.cs (pour le fichier RefCustomers.cs => RefCustomers.metadata.cs).

Ce fichier contient du code mort (inutile d'ajouter des méthodes) : il ne sert qu'à permettre la précision des caractéristiques des membres de l'entité métier.

La validation des données est réalisée grâce aux System.ComponentModel.DataAnnotations (ce mécanisme est basé sur la réflexion).

Leur fonctionnement est le suivant : dans le code, les membres sont décorés par des attributs de validation (StringLenght,etc.). Lors de l'exécution, .net analyse (réflexion) la classe afin de connaître les règles de validation (réalisé une seule fois).

Puis, avant l'affectation de valeurs, la validation est exécutée sur la nouvelle valeur. Dans le cas où cette dernière est invalide, une System.ComponentModel.DataAnnotations.ValidationException est lancée.

Exemple : le champ ContactName du Customers ne peut dépasser 25 caractères, je peux donc décorer le champ ContactName contenu dans le fichier de métadonnées d'un StringLengthAttribute.

Lors de l'exécution, la règle appliquée sera validée dans l'application cliente et l'application serveur.

Le fichier ressemble à ceci : (intègre l'exemple du StringLengthAttribute)

 

Sélectionnez

#pragma warning disable 649    // disable compiler warnings about unassigned fields

namespace NorthWindRIA.Web.Metier
{
    using System;
    using System.Collections.Generic;
    using System.ComponentModel;
    using System.ComponentModel.DataAnnotations;
    using System.Data.Objects.DataClasses;
    using System.Linq;
    using System.Web.DomainServices;
    using System.Web.Ria;
    using System.Web.Ria.Services;


    // The MetadataTypeAttribute identifies CustomersMetadata as the class
    // that carries additional metadata for the Customers class.
    [MetadataTypeAttribute(typeof(Customers.CustomersMetadata))]
    public partial class Customers
    {

        // This class allows you to attach custom attributes to properties
        // of the Customers class.
        //
        // For example, the following marks the Xyz property as a
        // required field and specifies the format for valid values:
        //    [Required]
        //    [RegularExpression("[A-Z][A-Za-z0-9]*")]
        //    [StringLength(32)]
        //    public string Xyz;
        internal sealed class CustomersMetadata
        {

            // Metadata classes are not meant to be instantiated.
            private CustomersMetadata()
            {
            }

            public string Address;

            public string City;

            public string CompanyName;

            [StringLength(25)] // Attribut ajouté pour limiter le nombre de caractères
            public string ContactName;

            public string ContactTitle;

            public string Country;

            public string CustomerID;

            public string Fax;

            public EntityCollection<Orders> Orders;

            public string Phone;

            public string PostalCode;

            public string Region;
        }
    }
}

#pragma warning restore 649    // re-enable compiler warnings about unassigned fields

Dans le cas où aucun attribut n'est précisé, ce sont les caractéristiques du modèle de données qui sont utilisées (longueur de chamP.-S., champ indispensable, etc.).

Dans l'arborescence, nous retrouvons alors ceci :

Attention : côté données, dans la version du PDC (nov 2009) RIA ne supporte pas les PK (clé primaire) multicomposites utilisées comme PK-FK (FK = clé étrangère) dans une autre table. Donc, une bonne habitude (avec RIA) consiste à utiliser un ID propre, + une contrainte d'unicité sur les chamP.-S. pour éviter les problèmes.

Une fois la création du service réalisée, il ne reste qu'à générer le projet.

1. Générer le projet web.
2. Générer le projet Silverlight.

Si d'aventure, la curiosité vous pique;), je vous invite à déployer toute l'arborescence du projet silverlight.

Déploiement de l'arborescence

1. Faites un clic sur le projet Silverlight,
   
   
2. Faites un clic sur l'icône « Show All Files »
   
   
3. Éventuellement sur « Refresh » (on ne sait jamais)
   

L'arborescence affiche alors les répertoires et fichiers qui ne font pas partie du projet.


Le répertoire qui nous intéresse plus particulièrement est « Generated_Code ».
Nous y retrouvons les classes générées par le moteur RIA lors du Build du projet Silverlight.
Je vous invite à consulter le fichier généré : cela vous permettra de mieux comprendre la logique des classes générées. Exemple : quelles sont les opérations effectuées lors de l'affectation de valeur ?

Lors de l'appel à la méthode Load (mais le propos vaut également pour les autres opérations disponibles), il est possible de préciser si une exception doit être propagée dans le client en cas d'exception lors de l'appel au serveur (dernier paramètre booléen des méthodes d'appel). Si l'exception est activée, se produit et n'est pas gérée par le code du développeur, cette dernière sera renvoyée à la méthode App.Application_UnhandledException.

Il y a plusieurs moyens de vérifier que les traitements n'ont pas renvoyé d'exceptions.

Considérons en deux :
- - l'expression lambda ou « CallBack method » ;
- - l'abonnement à l'événement Completed de l'objet renvoyé lors de l'appel ;

« CallBack method » ou expression lambda
P.-S. L'expression Lambda demeure ma technique favorite.

Ce moyen s'utilise le plus facilement du monde : lors de l'appel à l'opération, un des paramètres possibles est de type « Action{LoadOperation} », « Action{SubmitOperation} » ou « Action{InvokeOperation} ».
Il suffit dès lors d'utiliser une expression lambda d'exécution afin de gérer le retour.

Exemple :

monContexte.Load<Customers>(
    monContexte.GetCustomersQuery(),
    <BR>    // EXPRESSION LAMBDA : 
    loadOperation =>
         {
              if (loadOperation.HasError)
              {
                  MessageBox.Show(loadOperation.Error.Message);
                  loadOperation.MarkErrorAsHandled();
              }
         }, 
    // FIN D'EXPRESSION LAMBDA
    null);

Abonnement à l'événement Completed

Dans ce deuxième cas de figure, lors de l'appel à l'opération (Load, Submit ou Invoke), un objet de type LoadOperation (ou SubmitOperation, ou InvokeOperation) est retourné. Il suffit de s'abonner à l'événement « Completed » afin d'être averti de la fin du traitement (cf. ci-dessus « Exécution de la requête » et récupération des résultats événements événements…).

Dans les deux cas, l'objet qui contient les résultats de l'appel est identique, il est soit de type « LoadOperation », soit « SubmitOperation » ou encore « InvokeOperation ».

La gestion d'un retour se réalise alors en trois parties.

1. Tester si une erreur est présente.
   
2. Si c'est le cas : appeler « MarkErrorAsHandled ».
   Lorsque l'exception a été traitée, il ne faut pas oublier d'appeler la méthode « MarkErrorAsHandled() ». Cela va indiquer à RIA que l'exception a été traitée et qu'il ne faut pas la propager au reste de l'application. De même qu'il est possible de vérifier si l'exception a déjà été traitée par la propriété « IsErrorHandled ».
   
3. Gérer l'erreur.

Le code ci-dessous trace le cheminement :

// Appel de Submit changes en passant une expression lambda appelée au retour de l'appel !
monContexte.SubmitChanges(
     submitOp => // Expression lambda !
     {
          // code qui traite le retour avec gestion des erreurs
          
          if (submitOp.HasError) // Erreur présente ?
          {
               submitOp.MarkErrorAsHandled(); // permet d'éviter de diffuser l'exception comme irrémédiable !

               if (submitOp.Error != null)
               {
                    // traitement de l'objet Erreur (type Exception)
               }
               // traitement commun à toutes les erreurs
          }
     }, 
     null);

namespace NorthWindRIA
{
    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Windows.Ria;

    /// <summary>
    /// Classe d'extension sur un <see cref="LoadOperation{T}"/>
    /// </summary>
    public static class LoadOperationExtender
    {
        /// <summary>
        /// Traite le retour d'un appel au serveur pour les LoadOperations.
        /// Affiche éventuellement un message d'erreur à l'utilisateur si une erreur s'est produite.
        /// </summary>
        /// <typeparam name="T">Type d'objet retourné par la LoadOperation (<see cref="Entity"/>>)</typeparam>
        /// <param name="loadOp"><see cref="LoadOperation"/> qui a été utilisée pour l'appel au serveur</param>
        /// <returns><see cref="List{T}"/>La liste est vide en cas d'erreur (non nulle)</returns>
        public static List<T> TraiteRetour<T>(this LoadOperation<T> loadOp)
            where T : Entity
        {
            List<T> returnedList = new List<T>(); // par sécurité, la liste n'est jamais nulle !

            if (loadOp.Error != null)
            {
                loadOp.MarkErrorAsHandled();

                /* Méthode statique située dans la classe App qui permet de 
                 * traiter les erreurs de façon commune à toute l'app */
                App.TraiteErreur(loadOp.Error); 
            }
            else if (loadOp.Entities == null && !loadOp.Entities.Any())
            {
                /* Méthode statique située dans la classe App qui permet de 
                 * traiter les erreurs de façon commune à toute l'app */
                App.TraiteErreur("Le serveur n'a renvoyé aucune entité de type " + typeof(T).ToString() + " ! ");
            }
            else
            {
                returnedList = new List<T>(loadOp.Entities);
            }

            return returnedList;
        }
    }
}

}

namespace NorthWindRIA
{
    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Windows.Ria;

    /// <summary>
    /// Extender de la classe <see cref="SubmitOperation"/>
    /// </summary>
    public static class SubmitOperationExtender
    {
        /// <summary>
        /// Traite le retour d'un appel au serveur pour les <see cref="SubmitOperation"/>.
        /// Affiche éventuellement un message d'erreur à l'utilisateur si une erreur s'est produite.
        /// </summary>
        /// <param name="submitOp"><see cref="SubmitOperation"/> qui a été utilisée pour l'appel au serveur</param>
        /// <returns>Boolean : False si le retour est en erreur</returns>
        public static Boolean TraiteRetour(this SubmitOperation submitOp)
        {
            Boolean returned = true;

            if (submitOp.Error != null)
            {
                submitOp.MarkErrorAsHandled();
                returned = false;

                /* Méthode statique située dans la classe App qui permet de 
                 * traiter les erreurs de façon commune à toute l'app */
                App.TraiteErreur(submitOp.Error);
            }

            return returned;
        }
    }
}

}

namespace NorthWindRIA
{
    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Windows.Ria;

    /// <summary>
    /// Classe d'extension sur un <see cref="InvokeOperation"/>
    /// </summary>
    public static class InvokeOperationExtender
    {
        /// <summary>
        /// Traite le retour d'un appel au serveur pour les <see cref="InvokeOperation"/>.
        /// Affiche éventuellement un message d'erreur à l'utilisateur si une erreur s'est produite.
        /// </summary>
        /// <param name="invokeOp"><see cref="InvokeOperation"/> qui a été utilisée pour l'appel au serveur</param>
        /// <returns>Boolean : False si le retour est en erreur</returns>
        public static Boolean TraiteRetour(this InvokeOperation invokeOp)
        {
            Boolean returned = true;

            if (invokeOp.Error != null)
            {
                invokeOp.MarkErrorAsHandled();
                returned = false;

                /* Méthode statique située dans la classe App qui permet de 
                 * traiter les erreurs de façon commune à toute l'app */
                App.TraiteErreur(invokeOp.Error); 
            }

            return returned;
        }
    }
}


}

À l'utilisation de ces extensions, le code se résume donc à ceci :

var results = loadOp.TraiteRetour(); // pour une LoadOperation


if(submitOp.TraiteRetour()) // pour une SubmitOperation 
{
    // ...
}
else
{
    // ...
}


if(submitOp.TraiteRetour()) // pour une InvokeOperation 
{
    // ...
}
else
{
    // ...
}

Il est possible d'améliorer le détail des exceptions qui se propagent depuis le serveur.
Il suffit de modifier le nœud customErrors contenu dans le fichier web.config de l'application web qui héberge les DomainServices.

     <customErrors mode="On" defaultRedirect="?" />

Si la balise « customErrors » est définie (valeur « On » ou « RemoteOnly »), et que l'application ne s'exécute pas à partir de la machine qui l'héberge, le détail du message ne sera pas propagé au client. L'exception sera toujours présente, mais disposera d'un message réduit du type « Load operation failed for query 'xxx' ? ». Le type de l'exception sera toujours System.Windows.Ria.DomainOperationException.

L'exemple précédent utilise un terme que je n'ai pas encore abordé : Detach() et en l'abordant, il faut parler également de son jumeau : Attach(). Évitons les jalousies !

Pour extraire une entité, nous devons utiliser un contexte de données (le proxy qui permet d'interroger la classe Domain Service).

Lorsque l'extraction est réalisée : les entités sont liées au contexte d'extraction.

Cette liaison est comme la remorque d'une voiture : si elle n'est pas attachée, elle ne sert pas à grand-chose (hormis pour stocker le barda du garage dedans…).

Lorsque la remorque est attachée, elle devient utile (puisqu'il devient possible de l'utiliser pour déplacer des objets).

Dernière précision, une remorque ne peut être attachée qu'à un véhicule à la fois (comme pour les entités).

La méthode Detach() permet de désolidariser la remorque de la voiture, donc de détacher l'entité de son contexte. Du coup, si une opération est effectuée avec le contexte de données, cette opération ne tiendra pas compte de l'entité détachée ! (Exemple SubmitChanges ne prendra pas en compte les modifications à sauvegarder en Db pour l'entité détachée).

La méthode Attach() permet de placer le timon de la remorque sur la boule de la voiture, donc de lier l'entité à un contexte de données.

Lorsque cette liaison est effectuée : l'entité liée n'est pas marquée comme modifiée. Elle est donc considérée comme identique à la l'information stockée en base de données.

Un dernier point avant de terminer ce tutoriel : lorsqu'une propriété d'une entité est modifiée, un flag passe l'entité à HasChanges = true !

C'est sur la base de cette valeur qu'un contexte de données sait qu'au prochain SubmitChanges, il faut envoyer l'entité modifiée.

Ce mécanisme de flag ne fonctionne que si l'entité est attachée à un contexte de données.

Donc, instancier un objet, le modifier et ensuite l'attacher n'engendrera aucune modification en base de données lors du SubmitChanges().

Pour ajouter une entité, il est nécessaire d'appeler le contexte de données, la collection des entités concernées et enfin la méthode add.
Exemple :

monContexte.Customers.Add(nouvelleEntiteCustomer);
 monContexte.SubmitChanges(); // peut être appelé pour enregistrer plusieurs modifications en une fois !