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.