Cette nouvelle version amène beaucoup de nouveautés que je vous propose de découvrir dans cet article. La librairie a été testé avec succès sur différentes cartes animées par un ESP8266 (ESP-01, 05, 07 et D1 Mini) ainsi qu’un Arduino/Genuino MKR1000.

Pour la mise à jour, téléchargez la libraire ci-dessous et dézippez les fichiers dans le dossier “Constellation” dans votre répertoire de libraire Arduino.

Attention : cette version 2.x de la librairie Constellation pour Arduino/ESP nécessite la version 1.8.1.16249 ou plus récente du serveur Constellation pour fonctionner correctement. Pour mettre à jour votre plateforme Constellation, lancez le Web Platform Installer.

Réception de message et StateObject “asynchrone”

Il s’agit d’une grosse évolution par rapport à la version 1.x. Pour “récupérer” du serveur Constellation les messages à destination de votre package virtuel ou les StateObjects pour lequel votre package (virtuel) s’est abonné, il faut invoquer les actions “GetMessages” et “GetStateObjects” sur l’interface REST.

Ces méthodes supportent le “long-polling” c’est à dire qu’elles mettent en attente la requête tant qu’il n’y a pas de messages ou StateObjects à retourner avec la notion de timeout (par défaut 60 secondes).

Le problème sur les versions 1.x de la libraire Arduino est que le client HTTP est “synchrone”, c’est à dire qu’il envoi la requête HTTP et attend la réponse du serveur pour traitement ce qui est incompatible avec du long-polling car cela bloquerait le code de l’Arduino. De ce fait, les anciennes versions spécifiées le “timeout” de ces requêtes à 1 seconde.

Ainsi jusqu’à maintenant, l’interrogation des messages et SO pouvaient bloquer jusqu’à 2 secondes votre Arduino (1 seconde pour le GetMessage et 1 seconde pour le GetStateObject) et engendrait donc 1 requêtes HTTP toutes les secondes entre votre ESP/Arduino et le serveur Constellation.

Dans cette nouvelle version, la librairie utilisent 3 clients HTTP différents : un pour toutes les requêtes synchrones, un pour la réception de message (GetMessage) et un pour la réception des StateObjects (GetStateObjects).

Le client synchrone est donc toujours disponible et il n’y a aucun blocage, aucune attente pour la réception de message et de SO. De plus il n’y a plus besoin de “poller” ou “flooder” le serveur d’une requête toute les secondes, en réactivant le long-polling le 2ème et 3ème client HTTP, on lance une requête toutes les minutes (60 sec par défaut) dans l’attente de message et SO.

De ce fait, il y a quelques modifications à apporter dans votre code !

Premièrement, vous ne devez plus passer la référence de votre client réseau mais plutôt spécifier le type de votre client dans le template de la classe Constellation. Par exemple, si vous utilisez un ESP8266 ou un Arduino MKR1000, vous utiliserez la classe “WifiClient “” :

/* Create the Constellation client */
Constellation<WiFiClient> constellation("constellation.monserveur.com", 8088, "MyVirtualSentine", "MyPackage", "MyAccessKey123!");

Ensuite, il n’y a plus besoin d’invoquer la méthode “poll” dans votre boucle principale avec un timer, vous devez tout simplement appeler la méthode “loop” autant de fois que vous voulez :

void loop(void) {
  // Process incoming message & StateObject updates
  constellation.loop();
}

Cette méthode vérifie en fait si il y a eu une réponse sur le client utilisé pour la réception de message et sur le client pour la réception de SO afin de les dispatcher dans votre code.

Support du PackageDescriptor

Autre nouveauté majeure pour cette version 2, le support du “Package Descriptor”.

Pour rappel le “Package Descriptor” est un objet envoyé par un package au serveur pour décrire ses StateObjects et ses MessageCallbacks exposés par le package.

Le MessageCallback Explorer de la Console Constellation s’appuie sur le “Package Descriptor” de chaque package pour lister chaque MessageCallback avec un formulaire de test. Sans cette description cela serait impossible !

Les versions 1.x ne supportaient pas “Package Descriptor”, de ce fait il n’était pas possible d’explorer/découvrir les MessageCallbacks d’un package Arduino/ESP. Vous devez nécessairement connaitre par vous même les MC exposés par le package et le type des StateObjects qu’il pouvait publier.

Avec la version 2.0, l’Arduino/ESP envoie au serveur la description des MC exposés et des types utilisés par les SO et arguments des MC.

Dans la suite de cet article, vous découvrirez comment ajouter des types dans la description de votre package, mais n’oubliez jamais d’envoyer votre “Package Descriptor” en invoquant la méthode “declarePackageDescriptor”, typiquement une fois votre code Arduino initialisé (par exemple à la fin de la méthode setup()) :

// Declare the package descriptor
constellation.declarePackageDescriptor();

Amélioration du PushStateObject

La méthode “PushStateObject” permet de publier un StateObject sur le serveur Constellation.

Tout d’abord la méthode expose des surcharges vous permettant de spécifier comme “value” de votre SO des int, uint, double, float, long et bool et supporte en paramètre optionnel le “lifetime”, c’st à dire la durée en seconde de “vie” de votre StateObject avant d’être considéré comme expiré.

// Dummy data
uint16_t lux = 123;

// Push a simple type on Constellation 
constellation.pushStateObject("DemoLux", lux);  

// Push a simple type on Constellation with lifetime of 20 seconds
constellation.pushStateObject("DemoLux", lux, 20);

Vous pouvez toujours publier des StateObjects dont la valeur (value) est un objet complexe (formaté en JSON).

Le JSON peut être formaté sous forme d’une chaine de caractère avec la méthode “stringFormat” :

// Push a complex object on Constellation with stringFormat
constellation.pushStateObject("DemoLux", stringFormat("{ 'Lux':%d, 'Broadband':%d, 'IR':%d }", lux, full, ir));

Vous pouvez également définir votre propre type pour ce StateObject, par exemple nommons cet objet “MyLuxData” :

constellation.pushStateObject("DemoLux", stringFormat("{ 'Lux':%d, 'Broadband':%d, 'IR':%d }", lux, full, ir), "MyLuxData");

Sans oublier d’ajouter ce type “personnalisé” dans le “package descriptor”. Par exemple, dans le “setup()” et avant de faire un “declarePackageDescriptor”, on aurait décrit “MyLuxData” de la façon suivante :

constellation.addStateObjectType("MyLuxData", TypeDescriptor().setDescription("MyLuxData demo").addProperty("Broadband", "System.Int32").addProperty("IR", "System.Int32").addProperty("Lux", "System.Int32"));

Pour finir, vous pouvez toujours publier un StateObject en construisant la valeur dans un objet JsonObject de façon suivante :

// Push a complex object on Constellation with JsonObject
const int BUFFER_SIZE = JSON_OBJECT_SIZE(5);
StaticJsonBuffer<BUFFER_SIZE> jsonBuffer;
JsonObject& myStateObject = jsonBuffer.createObject();
myStateObject["Lux"] = lux;
myStateObject["Broadband"] = full;
myStateObject["IR"] = ir;
constellation.pushStateObject("DemoLux", myStateObject);

Dans les surcharges de cette méthode, vous pouvez également spécifier le type de votre StateObject et/ou sa durée de vie :

constellation.pushStateObject("DemoLux", myStateObject, "MyLuxData", 20);

Pour finir, nouveauté de la librairie 2.0, vous pouvez également spécifier des “meta-données” à vos StateObjects. Par exemple :

// Ajout de metadatas au StateObject
JsonObject& metadatas = jsonBuffer.createObject();
metadatas["ChipId"] = ESP.getChipId();
metadatas["Timestamp"] = millis();
constellation.pushStateObject("DemoLux", myStateObject, "MyStateObject", 20, &metadatas);

Les StateObjectLinks

En version 1.x de la librairie Arduino, vous pouvez :

• interroger des StateObjects de la Constellation en invoquant la méthode “requestStateObjects” qui vous retourne les StateObjects à l’instant T correspondant à votre requête :

// Example : print the all SO's value named "/intelcpu/0/load/0" and produced by the "HWMonitor" package (on all sentinels)
JsonArray& cpus = constellation.requestStateObjects("*", "HWMonitor", "/intelcpu/0/load/0");
for(int i=0; i < cpus.size(); i++) { 
  constellation.writeInfo("CPU on %s is currently %d %", cpus[i]["SentinelName"].asString(), cpus[i]["Value"]["Value"].as<float>());
}

• vous abonnez aux mises à jour des StateObjects pour être notifié en temps réel des que les SO changent :

// set a StateObject update callback and subscribe to SO
constellation.setStateObjectUpdateCallback([] (JsonObject& so) {
constellation.writeInfo("StateObject updated ! StateObject name = %s", so["Name"].asString()); 
});
// Subscribe to SO named "/intelcpu/0/load/0" and produced by the "HWMonitor" package (on all sentinels)
constellation.subscribeToStateObjects("*", "HWMonitor", "/intelcpu/0/load/0");

Vous pouvez invoquer plusieurs fois la méthode “subscribeToStateObjects” pour ajouter des abonnements à d’autre StateObjects mais il n’y a qu’un seul callback de réception des SO (défini par la méthode setStateObjectUpdateCallback). C’est à vous de “dispatcher” les SO reçus.

La nouveauté en 2.0 vient de l’ajout de la méthode “registerStateObjectLink” qui vous permet d’associer un callback à un abonnement laissant ainsi à la librairie la charge du “dispatch”.

Par exemple, on peut désormais écrire :

constellation.registerStateObjectLink("*", "HWMonitor", "/intelcpu/0/load/0", [](JsonObject& so) {
  constellation.writeInfo("CPU on %s is currently %d %", so["SentinelName"].asString(), so["Value"]["Value"].as<float>());
});

Ici on enregistre un “StateObject Link” sur tous les SO nommés « /intelcpu/0/load/0 » produits par le package “HWMonitor” de toutes les sentinelles de votre Constellation. Dès qu’un de ces StateObjects changent on exécutera le callback associé, qui ici écrit dans le log un message indiquant la nouvelle valeur du CPU.

Vous bien entendu enregistrer autant de StateObjectLink que vous souhaitez.

Enregistrement des MessageCallbacks

Le principe est le même que celui décrit ci-dessus pour les abonnements aux StateObjects.

En version 1.x, on devait définir un callback pour réception de message et invoquer la méthode “subscribeToMessage” :

// Set callback for all incoming messages
 constellation.setMessageReceiveCallback([](JsonObject& json) { 
   constellation.writeInfo("Message receive ! Message key = %s", json["Key"].asString());     
 }); 
 // Subscribe to message
 constellation.subscribeToMessage();

C’était donc à votre charge de “dispatcher” les messages reçus en fonction du “MessageKey”.

Désormais avec la version 2.0, vous pouvez enregistrer un callback pour un “MessageKey” donné. Par exemple :

constellation.registerMessageCallback("HelloWorld",
  [](JsonObject& json) {
    constellation.writeInfo("Hello Constellation !");
 });

Dans l’exemple ci-dessous, on ajoute/expose un MessageCallback “HelloWorld” qui écrit dans les logs !

Il n’y donc plus besoin de “dispatcher”, un MessageCallback est donc associé à un “MessageKey” unique et un callback. Il n’y a plus besoin non plus de faire un “subscribeToMessage” (cette méthode est invoquée implicitement par le registerMessageCallback).

De plus cette méthode ajoute implicitement les MessageCallbacks dans le Package Descriptor de sorte que chaque MC soit ainsi référencé dans la Constellation

(console)

Vous pouvez également passer un “MessageCallbackDescriptor” dans l’enregistrement de vos MC pour ajouter une description par exemple :

constellation.registerMessageCallback("HelloWorld",
  MessageCallbackDescriptor().setDescription("Say Hello to Constellation"),
  [](JsonObject& json) {
    constellation.writeInfo("Hello Constellation !");
 });

Et même définir les paramètres de vos MC :

constellation.registerMessageCallback("SayHello",
  MessageCallbackDescriptor().setDescription("Say hello !").addParameter("FirstName", "System.String").addParameter("LastName", "System.String"),
  [](JsonObject& json) {
    constellation.writeInfo("Hello %s %s", json["Data"][0].asString(), json["Data"][1].asString()); 
 });

Ici on déclare un MC nommé “SayHello” prenant deux paramètres de type String avec un texte de description. Dans la code nous verrons :

(console)

Tout comme les StateObjects, les types des arguments des MC peuvent être des types complexes.

Par exemple enregistrons un MC prenant un seul argument de type “SampleUserData” que nous allons décrire avec la méthode “addMessageCallbackType” comme un objet composé de deux propriétés de type String :

// Expose a MessageCallback with complex parameter :
constellation.registerMessageCallback("SayHello2",
  MessageCallbackDescriptor().setDescription("Say hello with complex object!").addParameter("User", "SampleUserData"),
  [](JsonObject& json) {
    constellation.writeInfo("Hello %s %s", json["Data"][0]["FirstName"].asString(), json["Data"][0]["LastName"].asString()); 
});  
// and describe the complex parameter "SampleUserData"  
constellation.addMessageCallbackType("SampleUserData", TypeDescriptor().setDescription("This is a smaple user data").addProperty("FirstName", "System.String").addProperty("LastName", "System.String"));

Enfin la méthode “registerMessageCallback” accepte également des callbacks prenant en paramètre le “MessageContext” :

constellation.registerMessageCallback("HelloWorld",
  MessageCallbackDescriptor().setDescription("Say Hello to Constellation"),
  [](JsonObject& json, MessageContext ctx) {
    constellation.writeInfo("Message received from %s", ctx.sender.friendlyName);
 });

L’objet “MessageContext” est défini de la façon suivante :

typedef struct {
    const char* sagaId;
    bool isSaga;
    const char* messageKey;
    MessageSender sender;
    ScopeType scope;
} MessageContext;

typedef struct {
    SenderType type;
    const char* friendlyName;
    const char* connectionId;
} MessageSender;

Vous pouvez donc récupérer les informations sur l’émetteur (Sender) du message, le scope et l’identifiant de Saga si c’est une saga (isSaga = true).

Support des Saga (messages avec réponse)

Une saga est un identifiant unique qu’on affecte à des messages pour les lier entre eux. Cela permet de faire des couples de message “Requête / Réponse”. Une “réponse” étant un message renvoyé à l’émetteur de la requête avec le même identifiant de saga pour que ce dernier puisse l’identifier comme la “réponse” à son message d’origine.

Vous pouvez exposer des MessageCallbacks qui “répondent”, c’est à dire des  MessageCallbacks qui retournent un message de réponse.

Par exemple, exposons un MC pour réaliser des Additions sur un Arduino. Vous enregistrerez un MC “Addition” prenant en parametre deux entiers et qui en retourne un (le résultat) :

constellation.registerMessageCallback("Addition",
  MessageCallbackDescriptor().setDescription("Do addition on this tiny device").addParameter("a", "System.Int32").addParameter("b", "System.Int32").setReturnType("System.Int32"),
  [](JsonObject& json, MessageContext ctx) {        
    int a = json["Data"][0].as<int>();      
    int b = json["Data"][1].as<int>();
    int result = a + b;
    constellation.writeInfo("Addition %d + %d = %d", a, b, result);      
    if(ctx.isSaga) {
      constellation.writeInfo("Doing additoon for %s (sagaId: %s)", ctx.sender.friendlyName, ctx.sagaId);   
    // Return the result :
      constellation.sendResponse<int>(ctx, result);
    }
    else {
      constellation.writeInfo("No saga, no response !");
    }
 });

Vous remarquerez dans le “MessageCallbackDescriptor” l’appel de la méthode “setReturnType” pour spécifier le type de retour (et que le fait qu’il s’agit d’un MC acceptant les sagas).

L’envoi de la réponse étant réalisé par la méthode sendReponse. Cette méthode a plusieurs surcharges :

template<typename T> bool sendResponse(MessageContext context, T data);
bool sendResponse(MessageContext context, const char* data, ...);
bool sendResponse(MessageContext context, JsonObject& data);

Notez aussi que vous devriez faire un “sendResponse” si et seulement le message reçu est associé à une saga, c’est à dire que le champs “isSaga” du contexte (MessageContext) est “vrai”. Sinon ca ne sert à rien de répondre

Pour finir, cette nouvelle version supporte également l’envoi de message dans une saga. C’est à dire que vous pouvez envoyer un message qui attend une réponse et donc enregistrer un callback de traitement de la réponse.

Par exemple le package “NetworkTools” expose un MC “Ping” permettant de faire un ping. Le package retourne dans la saga un message contenant le temps en milliseconde du ping. On pourrait alors invoquer cette méthode depuis notre Arduino de la façon suivante :

const char* ip = "192.168.0.10";
// Send message in a saga and attach a callback for response :
constellation.sendMessageWithSaga([](JsonObject& json) {
  constellation.writeInfo("Ping response in %s ms", json["Data"].asString()); 
}, Package, "NetworkTools", "Ping", "[ '%s' ]", ip);

Ici on envoi un message au scope “Package” pour atteindre le(x) package(s) “NetworkTools” afin d’invoquer le MessageCallback “Ping” en passant en argument l’IP à pinger. Vous remarquerez qu’on utilise le formatage implicite des arguments.

La méthode n’est pas la traditionnelle “sendMessage” mais “sendMessageWithSaga” qui prend un argument supplémentaire : le callback de traitement de la réponse.

Ainsi quand le package “NetworkTools” répondra, on executera le callback associé qui ici affichera le temps de réponse de notre ping (Data) dans les logs Constellation (writeInfo).

De ce fait, avec cette nouvelle libraire vos Arduino/ESP peuvent invoquer des MC dans sagas pour exploiter la réponse mais également exposer des MC qui retournent des résultats.

Autres nouveautés

En vrac, vous disposez maintenant une méthode “purgeStateObjects” permettant de supprimer des StateObjects de votre package.

De plus la méthode “setDebugMode” accepte en argument l’énumération “DebugMode” composée des valeurs suivantes :

• “Quiet” (mode silencieux, la libraire ne produit aucune trace dans l’interface Serial)
• “Normal” (mode par défaut, écrit quelques informations dans l’interface Serial)
• “Verbose” (écrit beaucoup d’information dans l’interface Serial comme par exemple les requêtes et réponse HTTP v ers Constellation)

Enfin les exemples fournis dans la libraire ont été complètement revus.

The post Nouvelle librairie Constellation pour Arduino / ESP8266 en version 2.0 appeared first on Constellation.

Message & Scope

Les notions de base du Messaging de Constellation sont :

Un message :

• porte obligatoirement une clé (le MessageKey), en quelque sorte l’équivalent du “Sujet” d’un mail.
• peut contenir optionnellement un contenu, nommé “Data”
• est envoyé à un scope.

Un scope :

• défini les destinataires d’un message
• peut être de différents types :
  • All : c’est à dire que tous les systèmes connectés dans Constellation recevront le message (y compris l’émetteur)
  • Other : tout le monde sauf l’émetteur
  • Package : cible un ou plusieurs packages
  • Sentinel : cible tous les packages hébergés sur les sentinelles visées par le scope
  • Group : cible les packages ou consommateurs appartenant aux groupes visés par le scope

Les scopes “Package”, “Sentinel” et “Group” peuvent déclarer une liste de packages, de sentinelles et de groupes.

• Lorsque l’on cible une sentinelle, on vise tous les packages qu’elle héberge.
• Lorsque l’on cible un package, on vise toutes les instances de ce package sur les sentinelles de votre Constellation.

Si vous voulez cibler un seul package en particulier, vous devez obligatoirement créer un scope de type Package et définir le nom du package préfixé du nom de la sentinelle avec la nomenclature “SENTINEL/Package”.

Chaque package ou consommateur peut s’inscrire à un groupe ou être inscrit d’office dans la configuration du serveur (lire l’article sur les groupes).

MessageCallback

Les messages dans Constellation servent essentiellement à invoquer des méthodes. On appelle cela des “MessageCallbacks” le fait de lier un message à une fonction de votre programme.

Il s’agit tout simplement déclarer une méthode de votre code comme « MessageCallback », c’est à dire que si le package reçoit un message dont la clé du message est le nom d’une méthode déclarée comme MessageCallback, alors cette méthode sera invoquée. Le contenu du message reçu (c’est à dire les “Datas”)  contiendra les paramètres de la méthode.

De la même façon, pour invoquer une méthode d’un autre package, il suffit d’envoyer un message dont la clé est la méthode à invoquer avec comme contenu de message les paramètres à passer à cette méthode.

Les Sagas

Chaque message envoyé dans Constellation est à sens unique. Il n’y a aucun retour.

Un message est envoyé à un scope,  il peut ne jamais être reçu (si « personne » n’est visée par le scope) ou à l’inverse être reçu par tout le monde.

Cependant il y a certain cas où il est indispensable d’obtenir une réponse à un message ! Comme en programmation, il n’y a pas que des procédures, il y a aussi des fonctions.

Pour cela, Constellation propose le concept de “Saga”. Une saga est un identifiant porté par un scope. Pour faire l’analogie, “La guerre des étoiles”, “L’Empire contre-attaque » ou “Le Retour du Jedi” sont trois films distincts qui portent le même identifiant de Saga : “Star Wars”.

Il en va de même pour les messages Constellation. Pour “répondre”, il suffit d’envoyer un message “de réponse” à un scope qui vise l’émetteur du message original en prenant soin d’utiliser le même identifiant de saga.

Ainsi l’émetteur en recevant ce message, pourra savoir qu’il s’agit de la réponse à son message car il retrouvera le même identifiant de saga.

Bien entendu l’identifiant de Saga doit être unique et aléatoire pour chaque couple “Request / Response” .

De ce fait, lorsque l’on reçoit un message, si le scope porte un identifiant de Saga cela veut dire que l’émetteur a envoyé le message “dans une Saga”, il s’attend donc à recevoir une réponse. Le clé d’un message de réponse est toujours “__Response”.

Auto-description des MessageCallbacks

Chaque packages (virtuel ou non) doit ou devrait déclarer son “Package Descriptor”.

Il s’agit de la description du package qui contient entre autre les MessageCallbacks du package, c’est à dire les méthodes que le package expose dans la Constellation.

Le MessageCallback Explorer de la Console Constellation exploite les “Package Descriptors” connus pour créer la liste de l’ensemble des MessageCallbacks exposés par les package d’une Constellation avec le détail des paramètres en entrée et le type de retour. Il est également possible d’invoquer ces MC avec une interface de test et de générer le code pour invoquer ces MC sur les différentes API de Constellation.

The post Messaging : Message, Scope, MessageCallback et Saga appeared first on Constellation.

Exposer des méthodes

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

[MessageCallback]
void MyMethod()
{
    PackageHost.WriteInfo("This is a MessageCallback !");
}

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 :

[MessageCallback]       
void MyMethodWithMultipleParameters(string input, int number, bool boolean)
{
    PackageHost.WriteInfo("Input= {0} - Number: {1} - Boolean: {2}", input, number, boolean);
}

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

[MessageCallback] 
void MyMethodWithComplexParameter(UserInfo user)
{
    PackageHost.WriteInfo("User: {0} & Password = {1}", user.User, user.Password); 
}

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 :

PackageHost.RegisterMessageCallbacks(source);

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 :

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

Vous pourrez alors directement tester vos MC depuis la Console :

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

Personnaliser le nom du MessageCallback

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

[MessageCallback(Key="Logon")]
void MyMethodWithComplexParameter(UserInfo user)
{
    PackageHost.WriteInfo("User: {0} & Password = {1}", user.User, user.Password);
}

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

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 :

[MessageCallback(IsHidden = true)]
void HiddenMethod()
{
    PackageHost.WriteInfo("This is a MessageCallback !");
}

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 :

[MessageCallback(IsHidden = true)]
void HiddenMethod()
{
    if(MessageContext.Current.Sender.FriendlyName == "SENTINEL-DEMO/MySafePackage")
    {
        PackageHost.WriteInfo("OK j’autorise le package MySafePackage de la sentinelle SENTINEL-DEMO");
    }
    else
    {
        PackageHost.WriteWarn("Je refuse que {0} puisse invoquer cette méthode !", MessageContext.Current.Sender.FriendlyName);
    }
}

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 :

[MessageCallback(Key="Logon", ResponseType=typeof(bool))]
void MyMethodWithComplexParameter(UserInfo user)
{
    PackageHost.WriteInfo("User: {0} & Password = {1}", user.User, user.Password);

    if (MessageContext.Current.IsSaga)
    {
        MessageContext.Current.SendResponse(user.User == user.Password);
    }
}

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 :

[MessageCallback(Key="Logon")]
bool MyMethodWithComplexParameter(UserInfo user)
{
    PackageHost.WriteInfo("User: {0} & Password = {1}", user.User, user.Password);

    return user.User == user.Password;
}

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 :

Vous pourrez alors tester votre MessageCallback :

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

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 :

/// <summary>
/// Methode d'identification d'un utilisateur.
/// </summary>
/// <param name="user">L'utilisateur à identifier.</param>
/// <returns><c>true</c> si identifié</returns>
[MessageCallback(Key="Logon")]
bool MyMethodWithComplexParameter(UserInfo user)
{
    PackageHost.WriteInfo("User: {0} & Password = {1}", user.User, user.Password);

    return user.User == user.Password;
}

/// <summary>
/// Classe decrivrant un utilisateur
/// </summary>
public class UserInfo
{
    /// <summary>
    /// Le nom d'utilisateur
    /// </summary>
    public string User { get; set; }

    /// <summary>
    /// Le mot de passe de l'utilisateur
    /// </summary>
    public string Password { get; set; }
}

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

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.

<sentinel name="PO-SWARIN" credential="StandardAccess">
    <packages>        
        <package name="HWMonitor" enable="true"></package>  
        <package name="ConstellationPackageConsole1" enable="true"></package> 
        <package name="MonPremierPackage" enable="true">
            <groups>
                <group name="MonGroupDemo" />
            </groups>
            <settings>
                <setting key="Interval" value="2000" />
            </settings>
        </package>  
    </packages>                
 </sentinel>

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 :

PackageHost.SubscribeMessages("MonGroupDemo");

The post MessageCallbacks : exposez vos méthodes appeared first on Constellation.

Créer un scope

Un message Constellation est envoyé à un Scope qui représente le ou les destinataires du message.

Un scope Constellation est décrit dans l’API.NET par la classe “MessageScope”. Vous pouvez créer un scope avec la méthode statique “Create”.

Par exemple pour créer un scope vers les instances du package “MonPackage” de votre Constellation  :

MessageScope.Create("MonPackage")

Par défaut le type de scope est “Package”. La ligne ci-dessus est donc identique à la ligne :

MessageScope.Create(MessageScope.ScopeType.Package, "MonPackage")

Si vous souhaitez cibler une instance d’un package en particulier, vous devez spécifier la sentinelle sur laquelle est hébergée le package que vous ciblez :

MessageScope.Create("MaSentinelle/MonPackage")

Si vous souhaitez cibler plusieurs packages :

MessageScope.Create(MessageScope.ScopeType.Package, "MonPackage", "MonAutrePackage", "EncoreUnAutrePackage")

Bien entendu vous pouvez donner le nom d’une instance en particulier (sentinelle + package) ou juste le nom du package :

MessageScope.Create(MessageScope.ScopeType.Package, "MaSentinelle/MonPackage", "MonAutrePackage")

Le scope “Sentinel” permet de cibler tous les packages sur une sentinelle donnée. Vous pouvez définir autant de sentinelle que vous souhaitez :

MessageScope.Create(MessageScope.ScopeType.Sentinel, "MaSentinelle", "MonAutreSentinelle")

Le scope “Group” permet de cibler les packages qui sont abonnés à un groupe. Ici créons un scope pour tous les packages membre du groupe “GroupA” :

MessageScope.Create(MessageScope.ScopeType.Group, "GroupA")

Vous pouvez bien sûr définir autant de groupe dans un scope que vous souhaitez :

MessageScope.Create(MessageScope.ScopeType.Group, "GroupA", "GroupB", "GroupC")

Enfin vous pouvez créer des scopes pour cibler tous les clients connectés dans votre Constellation (All) ou tout le monde sauf l’émetteur (Others). Dans ces deux cas, il n’y a pas d’argument à spécifier :

MessageScope.Create(MessageScope.ScopeType.Others)

Envoyer un message avec le SendMessage

La méthode de base pour envoyer un message dans Constellation est “PackageHost.SendMessage”.

Vous devez définir trois arguments pour envoyer un message :

• Le scope (les destinataires de votre message)
• La clé du message (MessageKey)
• Le contenu du message (Data)

Comme vous le savez, on se sert des messages pour invoquer des méthodes d’autre packages. La clé du message est en fait le nom de la méthode (= le MessageCallback) à invoquer.

Prenons pour exemple les MessageCallbacks définis dans l’article précédent.

Pour invoquer le MessageCallback “MyMethod” sans paramètre (Data = null) on pourrait écrire :

PackageHost.SendMessage(MessageScope.Create("MonPackage"), "MyMethod", null);

Pour une méthode avec plusieurs paramètres, ils faut les encapsuler dans un tableau d’objet :

PackageHost.SendMessage(MessageScope.Create("MonPackage"), "MyMethodWithMultipleParameters", new object[] { "Un String", 123, true });

Cela fonctionne aussi avec des objets complexes. Par exemple pour invoquer notre MessageCallback “Logon” :

PackageHost.SendMessage(MessageScope.Create("MonPackage"), "Logon", new { User = "seb", Password = "seb" });

Avec l’API .NET on ne se sert généralement jamais de cette méthode “SendMessage” car vous avez à disposition le “SendMessageProxy” que nous allons découvrir ci-dessous.

Envoyer un message avec un proxy dynamique

La classe “SendMessageProxy” est un objet dynamique qui permet d’envoyer un message de la même manière que vous appelez une méthode en programmation .NET.

Pour créer un proxy dynamique vous devez au préalable avoir créer votre scope :

MessageScope scope = MessageScope.Create("MonPremierPackage");
dynamic proxy = new SendMessageProxy(scope);

Pour simplifier le code, vous pouvez utiliser la méthode d’extension “GetProxy()” sur le MessageScope :

MessageScope scope = MessageScope.Create("MonPremierPackage");
dynamic proxy = scope.GetProxy();

Attention, pour accéder aux méthodes d’extension du MessageScope vous devez ajouter le namespace “Constellation.Package” :

using Constellation.Package;

Une fois le proxy  dynamique créé il suffit d’appeler ‘”fictivement” une méthode pour envoyer le message.

Par exemple pour envoyer le message “MyMethod” avec un contenu du vide, on écrira simplement :

proxy.MyMethod();

Si votre message doit contenir plusieurs arguments :

proxy.MyMethodWithMultipleParameters("Un String", 123, true);

Ou encore avec notre MessageCallback “Logon” qui prend en argument un objet complexe :

proxy.Logon(new { User = "seb", Password = "seb" })

Ainsi vous pouvez invoquer un MessageCallback de n’importe quel package de la même façon que vous invoquerez une méthode de votre code .NET. La méthode invoquée est la clé du message et les arguments sont inclus dans le contenu du message.

Bien sûr avec la méthode d’extension vous pouvez faire tout cela en une ligne de code : créer le scope, récupérer le proxy dynamique et envoyer le message :

MessageScope.Create("MonPremierPackage").GetProxy().Logon(new { User = "seb", Password = "seb" });

Vous avez également à disposition la méthode “CreateMessageProxy” sur le PackageHost. Cette méthode permet de créer un scope et vous retourne le proxy dynamique.

Les deux lignes ci-dessous sont donc identiques :

dynamic proxy = MessageScope.Create("MonPremierPackage").GetProxy();
dynamic proxy = PackageHost.CreateMessageProxy("MonPremierPackage");

De ce fait, pour invoquer nos trois MessageCallbacks, on peut écrire simplement :

PackageHost.CreateMessageProxy("MonPremierPackage").MyMethod();
PackageHost.CreateMessageProxy("MonPremierPackage").MyMethodWithMultipleParameters("Un String", 123, true);
PackageHost.CreateMessageProxy("MonPremierPackage").Logon(new { User = "seb", Password = "seb" });

Tout comme la méthode “MessageScope.Create”, le “CreateMessageProxy” peut créer tout type de scope.

Par exemple, invoquons le MessageCallbacks “MyMessageCallback” avec deux arguments (un string et un datetime) sur tous les packages du groupe A et B de notre Constellation :

PackageHost.CreateMessageProxy(MessageScope.ScopeType.Group, "GroupA", "GroupB").MyMessageCallback("Mon Argument", DateTime.Now);

Invoquer un MessageCallback avec réponse – Utilisation des Sagas

Lorsque vous envoyez un message dans un scope vous pouvez ajouter un identifiant de Saga sur ce scope. Cela indiquera au destinataire que vous souhaitez une réponse en retour (plus d’info).

L’identifiant de Saga doit être aléatoire et unique. Vous avez une méthode d’extension “WithSaga” sur un MessageScope vous permettant de définir l’identifiant de la saga (SagaId) avec un GUID :

MessageScope.Create("MonPremierPackage").WithSaga();

La méthode d’extension vous retourne le MessageScope, vous pouvez donc directement récupérer le proxy dynamique et envoyer votre message :

MessageScope.Create("MonPremierPackage").WithSaga().GetProxy().Logon(new { User = "seb", Password = "seb" });

Pour la réception des réponses, vous avez une méthode “RegisterSagaResponseCallback” qui permet d’enregistrer la fonction à invoquer lors de la réponse :

PackageHost.RegisterSagaResponseCallback(sagaId, (reponse) =>
{
      // Response pour la saga "sagaId"
});

Pour simplifier le code, vous avez une méthode d’extension “OnSagaResponse” sur un MessageScope qui permet à la fois d’ajouter un identifiant de saga sur le scope (WithSaga) et d’enregistrer la fonction de retour.

De ce fait, vous pouvez en une seule ligne créer votre scope avec saga, définir le code qui sera invoqué à la réception la réponse, récupérer le proxy dynamique et invoquer votre MessageCallback avec ses paramètres :

MessageScope.Create("MonPremierPackage").OnSagaResponse((response) =>
{
    // Reponse de la saga
}).GetProxy().Logon(new { User = "seb", Password = "seb" });

Comme pour les MessageCallbacks, la méthode de réception d’une réponse d’une saga est invoquée dans un thread dédié dans lequel vous avez accès au contexte du message via la propriété “MessageContext.Current”.

Vous pouvez donc savoir quel est le package qui vous a répondu (Sender) ou encore quel était l’identifiant de la saga utilisée.

De plus, notez que la méthode OnSagaResponse est générique afin de pouvoir définir le type de retour (le cast sera réalisé automatiquement).

On peut donc écrire :

MessageScope.Create("MonPremierPackage").OnSagaResponse<bool>((response) =>
{
    PackageHost.WriteInfo("Reponse de {0} pour la saga {1}",                 
        MessageContext.Current.SagaId,
        MessageContext.Current.Sender.FriendlyName);

    PackageHost.WriteInfo(response ? "OK" : "DENIED");

}).GetProxy().Logon(new { User = "seb", Password = "seb" });

Notez également que si votre scope cible plusieurs packages (ex : si “MonPremierPackage” est déployé sur plusieurs sentinelles), votre fonction de traitement de la réponse sera invoquée plusieurs fois, pour chaque package qui répondra (car l’identifiant de Saga est le même).

Utiliser les “Tasks” (awaitable) pour attendre la réponse d’une saga

C’est une nouveauté de la 1.8 de Constellation. Pour bien comprendre, résumons ce que l’on connait déjà !

Lorsque vous invoquez une méthode sur le proxy dynamique, celui-ci envoie un message dans Constellation où la clé du message est le nom de la méthode invoquée et le contenu du message sont les paramètres de la méthode invoquée.

Ces deux lignes sont donc identiques :

PackageHost.SendMessage(MessageScope.Create("MonPackage"), "Logon", new { User = "seb", Password = "seb" });
MessageScope.Create("MonPremierPackage").GetProxy().Logon(new { User = "seb", Password = "seb" });

Sur la 2ème ligne, vous invoquez dynamiquement la méthode “Logon” sur le SendMessageProxy (créé par la méthode GetProxy()) pour envoyer (PackageHost.SendMessage) le message “Logon”.

Ces deux lignes font donc bien la même chose. Dans les deux cas le message est envoyé dans un scope qui ne porte pas de “SagaId” (donc aucune réponse n’est attendue).

Je rappelle également que vous pouvez créer un scope et récupérer son proxy dynamique directement avec la méthode PackageHost.CreateMessageProxy. On peut donc encore simplifier le code par la ligne :

PackageHost.CreateMessageProxy("MonPremierPackage").Logon(new { User = "seb", Password = "seb" });

D’un point de vue .NET, l’invocation dynamique de notre MessageCallback  “Logon » sur le proxy dynamique ne retourne rien, du moins il retourne “null”.

object result = PackageHost.CreateMessageProxy("MonPremierPackage").Logon(new { User = "seb", Password = "seb" });
// ici result = null

Observez maintenant le code ci-dessous :

Task<dynamic> reponse = PackageHost.CreateMessageProxy("MonPremierPackage").Logon<bool>(new { User = "seb", Password = "seb" });

Si vous examinez attentivement le MessageCallback que nous invoquons sur le proxy dynamique, on utilise une forme générique : au lieu d’avoir “Logon(xxxxx)”, on a ”Logon<bool>(xxxxx)”

Le fait de définir un type générique indique au proxy dynamique que vous attendez une réponse et donc qu’il s’agit d’une saga !

Le type générique est le type de réponse que vous attendez. Ici le MessageCallback “Logon” que vous avons écrit dans l’article précédent renvoi un booléen (bool). Vous pouvez utiliser n’importe quel type de base ou types complexes.

Si c’est la réponse est un objet anonyme ou si vous n’avez pas la définition de l’objet de retour dans votre code,  vous pouvez utiliser un “dynamic” (ex Logon<dynamic>(xxxx)).

Quoi qu’il en soit il est obligatoire d’invoquer le MessageCallback  en utilisant la syntaxe générique pour que le proxy dynamique ajoute automatiquement un identifiant de saga (WithSaga) lors de l’envoi du message.

Revenons donc à notre appel :

Task<dynamic> reponse = PackageHost.CreateMessageProxy("MonPremierPackage").Logon<bool>(new { User = "seb", Password = "seb" });

Le proxy dynamique nous retourne une ”Task<dynamic>”, c’est à dire une tache qui se charge d’envoyer et d’attendre la réception de la (première) réponse.

Vous pouvez bloquer le thread appelant jusqu’à ce que l’opération asynchrone soit terminée,  c’est à dire jusqu’à l’obtention de la réponse :

Task<dynamic> reponse = PackageHost.CreateMessageProxy("MonPremierPackage").Logon<bool>(new { User = "seb", Password = "seb" });
PackageHost.WriteInfo((bool)reponse.Result ? "OK" : "DENIED");

Ajouter des timeouts

Comme vous bloquez le thread appelant, prenez garde de mettre des gardes fou car nous n’avez aucune garantie qu’un package va répondre à votre saga. La tache pourrait ne jamais être complétée! Vous devriez donc attendre un certain temps avant de considérer la tache “hors délai”.

Par exemple attendons pendant 3 secondes maximum pour une réponse à notre Saga “Logon” :

Task<dynamic> reponse = PackageHost.CreateMessageProxy("MonPremierPackage").Logon<bool>(new { User = "seb", Password = "seb" });
if (reponse.Wait(3000) && reponse.IsCompleted)
{
    PackageHost.WriteInfo((bool)reponse.Result ? "OK" : "DENIED");
}
else
{
    PackageHost.WriteError("Aucune réponse !");
}

Async/Await

Aussi vous pouvez utiliser le pattern async/await, très pratique pour les packages UI WPF/Winform :

public async void Logon()
{
    bool reponse = await PackageHost.CreateMessageProxy("MonPremierPackage").Logon<bool>(new { User = "seb", Password = "seb" });
    PackageHost.WriteInfo(reponse ? "OK" : "DENIED");
}

Résultat de la tache

Notez bien que le proxy dynamique vous renverra toujours une “Task<dynamic>” quelque soit le type générique précisé au niveau de l’appel du MessageCallback (“bool” dans l’exemple du “Logon”).

Cependant le résultat de la tache (Task.Result) est bien du type que celui passé au niveau de l’appel du MessageCallback.

Si vous souhaitez toutefois récupérer une Task<T> où T est le type de retour de votre saga, vous devez créer une nouvelle tache pour réaliser le “cast” à la suite de la tache créée par Constellation.

Par exemple :

Task<dynamic> task = PackageHost.CreateMessageProxy("MonPremierPackage").Logon<bool>(new { User = "seb", Password = "seb" });
Task<bool> logonTask = task.ContinueWith<bool>(t => (bool)t.Result);

Annuler les taches

Lorsque l’on créé des taches en .NET on peut avoir besoin de leurs associer un jeton d’annulation : le CancellationToken.

Pour cela, il vous suffit de passer un “CancellationToken” comme dernier argument de votre invocation du MessageCallback :

CancellationTokenSource source = new CancellationTokenSource(1000);
CancellationToken token = source.Token;
try
{
    Task<dynamic> reponse = PackageHost.CreateMessageProxy("ConstellationPackageConsole1").Logon<bool>(new { User = "seb", Password = "seb" }, token);
    PackageHost.WriteInfo("Result = {0}", reponse.Result);
}
catch (AggregateException ae)
{
    foreach (Exception e in ae.InnerExceptions)
    {
        if (e is TaskCanceledException)
            PackageHost.WriteError("Unable to compute mean: {0}", ((TaskCanceledException)e).Message);
        else
            PackageHost.WriteError("Exception: " + e.GetType().Name);
    }
}
finally
{
    source.Dispose();
}

Dans l’exemple ci-dessus on crée un CancellationToken à partir d’un CancellationTokenSource que l’on passe en tant que dernier paramètre du MessageCallback.

Le CancellationTokenSource est ici construit pour annuler la tache après 1 seconde (1000 ms). Vous pouvez aussi annuler la tache en en appelant la méthode “Cancel” sur l’objet CancellationTokenSource :

source.Cancel();

Bien entendu, le proxy dynamique se sert de votre CancellationToken pour savoir quand annuler la tache. De plus notez bien que le proxy retire ce CancellationToken des paramètres du message (= le CancellationToken n’est pas envoyé dans le message !).

Prenez garde à bien gérer les exceptions, si la tache est annulée une exception “TaskCanceledException” est levée.

Le contexte du message

Dans une méthode marquée comme “MessageCallback” ou dans le callback de retour d’une saga (OnSagaResponse) vous pouvez toujours accéder au contexte de réception du message avec la propriété “MessageContext.Current”.

En effet les MessageCallbacks ou les callbacks de retour des sagas sont invoqués dans un thread à part ce qui permet de l’attacher au contexte de réception du message.

Cependant avec les taches, le résultat est dispatché dans le thread de l’appelant. Autrement dit, vous ne pouvez pas accéder au contexte courant (MessageContext.Current) !

La solution consiste à “demander” au proxy dynamique de vous “remplir” un contexte que vous avez initialisé au préalable.

Pour ce faire, commencez par déclarer un contexte vide (MessageContext.None) et passer l’instance comme dernier paramètre d’un appel :

MessageContext context = MessageContext.None;
Task<dynamic> reponse = PackageHost.CreateMessageProxy("ConstellationPackageConsole1").Logon<bool>(new { User = "seb", Password = "seb" }, context);
PackageHost.WriteInfo("Result = {0} - Response received from : {1}", reponse.Result, context.Sender.FriendlyName);

Une fois la tache complétée, la variable “context” sera remplie avec le contexte de la réponse lors de la réception. Vous pourrez donc accéder au contexte même dans vos taches.

Le MessageContext est toujours le dernière paramètr et le CancellationToken est donc l’avant dernier paramètre dans le cas où vous utilisez les deux :

CancellationTokenSource source = new CancellationTokenSource(1000);
CancellationToken token = source.Token;
MessageContext context = MessageContext.None;
try
{
    Task<dynamic> reponse = PackageHost.CreateMessageProxy("ConstellationPackageConsole1").Logon<bool>(new { User = "seb", Password = "seb" }, token, context);
    PackageHost.WriteInfo("Result = {0} - Response received from : {1}", reponse.Result, context.Sender.FriendlyName);
}
catch (AggregateException ae)
{
    foreach (Exception e in ae.InnerExceptions)
    {
        if (e is TaskCanceledException)
            PackageHost.WriteError("Unable to compute mean: {0}", ((TaskCanceledException)e).Message);
        else
            PackageHost.WriteError("Exception: " + e.GetType().Name);
    }
}
finally
{
    source.Dispose();
}

Générateur de code

Comme l’ensemble des MessageCallbacks sont déclarés dans la Constellation (sauf si ils sont marqués comme “Hidden”), il est possible de générer du code. Vous pouvez lire un article très complet sur le sujet ici.

Dans le menu contextuel de votre projet Visual Studio, sélectionnez “Generate Code” :

Sélectionnez votre Constellation et cliquez sur “Discover” :

Sélectionnez le ou les packages que vous souhaitez invoquer depuis votre package et cliquez sur “Generate”.

Le générateur de code va créer différentes classes présentant votre Constellation avec les packages sélectionnés (MessageCallbacks et StateObjects).

Dans notre cas nous allons inclure la définition des MessagesCallbacks de notre package “MonPremierPackage”.

Commençons donc par ajouter le using vers le MessageCallbacks de MonPremierPackage :

using ConstellationPackageConsole1.MonPremierPackage.MessageCallbacks;

Dans la classe générée “MyConstellation” vous retrouverez la liste des sentinelles et packages de votre Constellation :

Vous pourrez alors créer un scope personnalisé pour le package sélectionné :

Ce scope personnalisé contiendra l’ensemble des MessageCallbacks :

Et sur chaque MessageCallback, vous retrouvez les bons types de retour, les commentaires et les types complexes proprement générés :

De ce fait, pour reprendre l’exemple du MessageCallback “Logon”, on pourra écrire le code :

var context = MessageContext.None;
var token = new CancellationTokenSource(5000).Token;
var user = new UserInfo() { User = "seb", Password = "seb" };

var task = MyConstellation.Packages.MonPremierPackage.CreateMonPremierPackageScope().Logon(user, token, out context);

PackageHost.WriteInfo("Logon user {0} - Result = {1} - Sender : {2}", user.User, task.Result, context.Sender.FriendlyName);

N’hésitez pas lire cet article très complet sur la génération de code C# dans Constellation.

The post Envoyer des messages & Invoquer des MessageCallbacks appeared first on Constellation.