Avant de tout, il est recommandé de lire cet article d’introduction aux concepts de Message, Scope, MessageCallback & Saga dans Constellation pour bien comprendre le principe des MessageCallbacks.

Exposer des méthodes

Pour exposer une méthode .NET dans Constellation, il suffit d’ajouter l’attribut “MessageCallback” sur une méthode :

Cela fonctionne que votre méthode soit privée ou public, d’instance ou statique.

Une méthode marquée MessageCallback peut accepter zéro, un ou plusieurs paramètres :

De plus chaque paramètre peut être de type simple ou complexe :

Par défaut seules les méthodes marquées [MessageCallback] sur votre classe ”IPackage” sont enregistrées.

Si vous souhaitez également enregistrer les MessageCallbacks référencés de vos autres types, vous devez appeler la méthode “RegisterMessageCallbacks” en passant en paramètre l’instance ou le type à enregistrer :

Testez vos MessageCallbacks depuis la Console Constellation

Si vous publiez votre package ou démarrer votre package depuis VS  avec les trois méthodes ci-dessus, vous retrouverez ces trois MessageCallbacks dans l’explorateur :

MessageCallback Explorer

Tout y est décrit, y compris les types complexes :

Description des types

Vous pourrez alors directement tester vos MC depuis la Console :

MessageCallback Explorer

Ce qui compte tenu du code donné en exemple ci-dessus affichera des messages dans les logs Constellation visible sur la Console Log :

Demo

Personnaliser le nom du MessageCallback

Vous pouvez également changer le nom du MessageCallback sans forcement changer le nom de votre méthode :

Ici la méthode se nomme toujours “MyMethodWithComplexParameter” dans notre code C# mais est vue dans Constellation comme le MessageCallback nommé “Logon” :

MessageCallback Explorer

MessageCallback caché

Vous pouvez aussi exposer des MessageCallbacks que vous ne souhaitez “rendre publique”. En d’autre mots, vous ne souhaitez pas que votre MC soit référencé dans la description de votre package.

Exemple : vous avez un package qui envoie des messages à un groupe pour prévenir de l’arrivée d’un événement (ex: le téléphone sonne). Vous souhaitez, dans le code de votre package, déclencher une méthode lorsque cet événement se produit. Autrement dit, vous créez une méthode marquée “MessageCallback“ qui porte le même nom que le MessageKey envoyé par l’autre package (le même nom de méthode ou via la propriété Key comme vu ci-dessus).

Ainsi, comme votre package fait partie du groupe cible, lorsque le téléphone sonne, l’autre package envoie un message au groupe, vous recevez donc le message et comme vous avez un MessageCallback du même nom, votre méthode est invoquée !

C’est parfait à l’exception que tout le monde “voit l’existence” de cette méthode et peuvent tous l’invoquer !

Deux solutions :

  • Cacher le MessageCallback (= ne pas le déclarer dans la description du package)
  • Vérifier l’émetteur

Pour cacher un MC, il suffit simple de définir la propriété “IsHidden” à vrai :

Ainsi la méthode, n’apparaîtra nulle part, personne ne pourra savoir que votre package “écoute” des messages dont la clé est ici “HiddenMethod”.

MessageContext

Vous pouvez, dans le code d’un “MessageCallback”, accéder au contexte du message reçu via la propriété “MessageContext.Current”.

Le contexte du message contient notamment le MessageSender (identifié de l’émetteur du message) et le MessageScope (scope dans lequel le message a été envoyé ).

Par exemple on pourrait écrire :

Répondre à une saga

Comme nous l’avons vu dans les concepts, il est possible de répondre à un message en renvoyant un message avec le même identifiant de saga. De ce fait, un MessageCallback peut renvoyer une réponse.

Dans la pratique, il suffit de regarder dans le contexte du message si c’est une saga (c’est à dire que le scope porte un identifiant de saga). Si c’est une saga, vous pouvez appeler la méthode d’extension “SendResponse” qui se chargera pour vous d’envoyer le contenu de votre message dans un scope portant le même identifiant de saga et à destination du package émetteur.

De plus, pour indiquer que le MessageCallback répond aux sagas, on indique quel est le type de l’objet de réponse dans l’attribut [MessageCallback] avec la propriété ResponseType.

Par exemple :

Avec Constellation 1.8, la syntaxe est encore plus simple. Vous pouvez simplement écrire votre MessageCallback avec une fonction .NET, c’est à dire une méthode qui retourne (return) une valeur :

La propriété “ResponseType” du MessageCallback est automatiquement définie avec le type de retour de la méthode. C’est l’API .NET qui se chargera d’envoyer la réponse si le message est reçu est une saga. La réponse renvoyée étant l’objet retourné par votre méthode, dans l’exemple ci-dessus un booléen.

Ainsi en republiant le package avec le code ci-dessus, vous constaterez dans le MessageCallbacks Explorer que votre MessageCallback indique son type de réponse dans le cas d’une saga :

MessageCallback avec saga

Vous pourrez alors tester votre MessageCallback :

Envoyer un message dans une saga

Et visualisez le message de retour, ici un booléen :

Réponse d'une saga

Décrire ses MessageCallbacks

Pour finir il est vivement conseillé de décrire ses MessageCallbacks et les types utilisés en paramètre ou en réponse.

Vous avez deux possibilités :

  • Utilisez la propriété “Description” sur l’attribut MessageCallback (mais limité aux MC et non aux types)
  • Utilisez les commentaires de documentation XML

Pour gagner en productivité, je vous recommande l’extension Visual Studio GhostDoc de SubMain pour générer automatiquement des commentaires de documentation XML dans votre code .NET.

Ainsi ajoutons des commentaires de documentation XML sur nos MessageCallbacks et sur la classe UserInfo utilisée dans nos exemples comme paramètre de notre MC :

Si vous redéployez le package, vous observerez que l’ensemble des MessageCallbacks et des paramètres sont décrits par vos commentaires XML :

MessageCallback documenté

S’abonner et recevoir les messages d’un groupe

Comme vous le savez, il existe plusieurs type de scope pour recevoir un message. Par défaut votre package recevra les messages adressés au scope “All” et “Other” (si il n’est pas l’émetteur du message) mais aussi et surtout ceux destinés au scope de sa sentinelle et/ou de son package.

Il y a un dernier type de scope fort utile : “les groupes”. Pour recevoir des messages destinés à un groupe, il faut d’abord s’abonner au groupe.

Vous avez deux manières d’ajouter votre package dans un groupe :

  • Depuis la configuration du serveur
  • Depuis le code de votre package

La première méthode se réalise dans la configuration de votre package directement dans la configuration du serveur Constellation.

Il suffit d’ajouter un élément “group” en indiquant les noms des groupes à rejoindre.

Ajout de groupe dans la configuration

Vous pouvez aussi utiliser la Console Constellation pour éditer les groupes de chaque package.

Autre manière, directement dans votre code en utilisant la méthode “PackageHost.SubscribeMessages” (ou PackageHost.UnsubscribeMessages).

Par exemple :

MessageCallbacks : exposez vos méthodes
Editer la page sur GitHub
Étiqueté avec :