Catégorie .NET API - Constellation

Créez votre premier package Constellation en C#

Sebastien Warin — Wed, 16 Mar 2016 10:00:22 +0000

Dans cet article nous allons découvrir comment créer et déployer votre premier package Constellation en C# avec Visual Studio.

Prérequis

Un accès “Administrator” à une Constellation (Management API & Developper access)
Le SDK Constellation installé

Nous vous conseillons de suivre le guide de démarrage ici avant de démarrer.

Créez le package dans Visual Studio

Lancez Visual Studio
Créez un nouveau projet de type “Constellation Package Console” (dans la catégorie Constellation) :

Démarrez le package en mode debug en cliquant sur le bouton “Start” ou en pressant la touche “F5” :

Au démarrage, votre package affichera une sorte de ”Hello World” :

Vous constaterez que :

La méthode “OnStart” est la méthode invoquée au démarrage de votre package
PackageHost.WriteInfo est une méthode pour écrire des logs de type “info”
PackageHost.IsRunning = true (votre package est bien en cours)
PackageHost.IsConnected = false (votre package n’est pas connecté à Constellation, car nous l’avons lancé en local)

Fonctionnement de base

Un package est une application !

Il faut impérativement appeler la méthode “PackageHost.Start” au démarrage de l’application, c’est à dire dans la méthode “Main” autrement, ce n’est pas un package Constellation mais une simple application !

Lorsque vous appelez la méthode “PackageHost.Start” vous devez impérativement transférer les arguments (args) et indiquer la classe de votre package qui est dans notre exemple “Program”.

static void Main(string[] args)
{
    PackageHost.Start(args);
}

La classe d’un package doit être une classe qui implémente l’interface “IPackage”. Cette interface définie trois méthodes :

OnStart qui sera invoqué lorsque le package a démarré
OnPreShutdown : invoqué lorsque le package va s’arrêter (à ce stade votre package est toujours connecté à Constellation, vous pouvez encore pusher des StateObjects, envoyer des messages, écrire des logs sur le hub, etc..)
OnShutdown : invoqué après le OnPreShutdown et après avoir fermé les connexions.

Pour vous éviter de devoir implémenter ces trois méthodes, votre classe peut hériter de la classe “PackageBase”. Cette classe abstraite implémente l’interface IPackage dans des méthodes virtuelles vides.

Libre à vous d’implémenter les méthodes que vous souhaitez !

Dans le template de projet créé ci-dessus, la classe “Program” hérite de “PackageBase” et redéfinie la méthode “OnStart” pour écrire un message de type “info” (PackageHost.WriteInfo) lorsque le package a démarré.

Ecrire des logs

Pour écrire des logs depuis un package Constellation vous disposez des méthodes :

PackageHost.WriteDebug
PackageHost.WriteInfo
PackageHost.WriteWarn
PackageHost.WriteError

Chacune de ces méthodes écrivent un message qui peut être formaté avec des arguments à la manière d’un “string.Format” :

PackageHost.WriteInfo("Je suis le package nommé {0} version {1}", PackageHost.PackageName, PackageHost.PackageVersion);

Attention : bien respecter les index dans le format de votre message sous peine d’avoir une erreur.

Note : la méthode WriteDebug écrit seulement dans la console (mode debug local). Les logs de type “Debug” ne sont jamais envoyés dans la Constellation.

Accéder aux settings

Chaque package peut définir des paramètres de configuration définis au niveau du serveur Constellation. Cela vous permet de changer ces paramètres directement depuis la Constellation qui se chargera de redescendre ces paramètres sur vos packages.

Il y a deux types de settings :

Les “Setting Value” : très simple il s’agit d’un couple clé/value à l’instant des d’une application .NET
Les “Setting Content” : au lieu de définir la valeur d’un paramètre dans un attribut XML, on peut la définir dans un élément XML enfant permettant d’avoir des settings qui renferme du XML ou JSON

Voici par exemple des “SettingValues” déclarés dans notre configuration :

Ces trois settings définissent la valeur dans l’attribut “value” (= SettingValue).

Pour récupérer la valeur du paramètre “MyStringSetting” dans votre code, utilisez la méthode “GetSettingValue” :

PackageHost.WriteInfo("My String = {0}", PackageHost.GetSettingValue("MyStringSetting"));

La méthode “GetSettingValue” renvoie la valeur d’un setting de type “string” mais vous pouvez également caster la valeur depuis cette méthode en utilisant sa forme générique :

int myIntSetting = PackageHost.GetSettingValue("MyIntSetting");
bool myBoolSetting = PackageHost.GetSettingValue("MyBoolSetting");

Si par contre vous avez un modèle de configuration plus compliqué qu’une série de clé/valeur vous pouvez utiliser les “Setting Contents” pour définir du XML ou JSON comme valeur de setting.

Par exemple la configuration de votre package peut définir deux autres settings, contenant du XML ou JSON de cette façon :


  
    
      Tove
      Jani
      Reminder
      Don't forget me this weekend!

Plusieurs méthodes pour récupérer ces settings :

GetSettingValue : vous pouvez toujours récupérer le contenu brute de votre setting sous forme d’un string
GetSettingAsJsonObject : dé-sérialise le contenu JSON de votre setting et vous retourne un objet dynamique
GetSettingAsJsonObject : dé-sérialise le contenu JSON de votre setting et le convertie dans un objet de votre type (T)
GetSettingAsXmlDocument : dé-sérialise le contenu XML de votre setting et vous retourne un XmlDocument
GetSettingAsConfigurationSection : dé-sérialise le contenu XML de votre setting sous forme d’un ConfigurationSection .NET

Par exemple, pour manipuler le setting XML on pourrait écrire :

var xml = PackageHost.GetSettingAsXmlDocument("MyXmlDocument");
PackageHost.WriteInfo("My XmlDocument Attribute = {0} , first node value = {1}", xml.ChildNodes[0].Attributes["date"].Value, xml.ChildNodes[0].FirstChild.InnerText);

Autre exemple avec le setting JSON :

dynamic json = PackageHost.GetSettingAsJsonObject("MyJsonObject");
PackageHost.WriteInfo("My JsonObject String={0}, Int={1}, Boolean={2}", json.String, json.Number, json.Boolean);

Les settings d’un package sont déclarés au niveau du serveur dans la déclaration du package et/ou dans le fichier App.config.

Tous les settings doivent être déclarés dans le manifeste du package (fichier PackageInfo.xml).

Retrouvez plus d’information sur les settings dans cet article.

Publier des StateObjects

Pour publier (Push) un StateObject dans Constellation vous devez invoquer la méthode “PackageHost.PushStateObject” en précisant obligatoirement le nom du StateObject et sa valeur.

Par exemple, vous pouvez publié n’importe quel type de base :

PackageHost.PushStateObject("MyString", "OK");
PackageHost.PushStateObject("MyNumber", 123);
PackageHost.PushStateObject("MyDecimal", 123.12);
PackageHost.PushStateObject("MyBoolean", true);

Pouvez également publié des objets anonymes :

PackageHost.PushStateObject("AnonymousObject", new { String = "test", Number = 123 });

Ou encore avec des types plus complexes :

PackageHost.PushStateObject("MyObject",  new MyCustomObject() { String = "test", Number = 123 });

Vous avez également la possibilité de définir des paramètres optionnels comme les métadonnées de votre StateObject ou sa durée de vie.

Par exemple, le StateObject “ShortLife” a une durée de vie de 20 secondes après sa publication. Au delà il sera marqué comme expiré.

PackageHost.PushStateObject("ShortLife", "Expire in 20 secs !!!", lifetime: 20);

Ici, on publie un StateObject “Salon” en lui associé les metadatas “Id” et “Zone”.

PackageHost.PushStateObject("Salon", monObjetZoneSalon, metadatas: new Dictionary { { "Id", 42 }, { "Zone", "Salon" } });

Sur les objets personnalisés il est recommande de décorer les classes de l’attribut [StateObject] si vous avez possibilité de modifier le code de la classe. Autrement, sur votre classe IPackage, ajoutez l’attribut [StateObjectKnownTypes] en définissant tous les types de StateObjects que vous serez amener à publier. Cela permet de décrire ces types dans la Constellation pour l’auto-description (utilisez entre autre par les générateurs de code).

Pour plus d’information sur les StateObjects dans l’API .NET cliquez ici.

Tester son package dans sa Constellation

Pour tester nous allons créer un package qui push à intervalle régulier un StateObject.

Le code de notre Package sera :

public class Program : PackageBase
{
    static void Main(string[] args)
    {
        PackageHost.Start(args);
    }

    public override void OnStart()
    {
        PackageHost.WriteInfo("Package starting - IsRunning: {0} - IsConnected: {1}", PackageHost.IsRunning, PackageHost.IsConnected);
        PackageHost.WriteInfo("Je suis le package nommé {0} version {1}", PackageHost.PackageName, PackageHost.PackageVersion);

        while (PackageHost.IsRunning)
        {
            PackageHost.WriteInfo("Je push un long !");
            PackageHost.PushStateObject("DemoLong", DateTime.Now.Ticks);

            Thread.Sleep(PackageHost.GetSettingValue("Interval"));
        }
    }
}

Notre application console démarre bien le package au démarrage (Main) où le package est notre classe Program qui hérite de PackageBase (donc c’est un IPackage).

Au démarrage on écrit deux logs de type information qui indique notamment le nom du package, sa version, si il est démarré (IsRunning) et si il est connecté (IsConnected).

Ensuite on crée une boucle qui tournera tant que le package est démarré. A chaque itération on écrit un log, publie un StateObject avant de mettre le thread en pause avant la prochaine itération.

Le temps de pause est un setting de type “Int” que l’on a nommé “Interval”.

L’utilisateur pourra le configurer dans la configuration du package sur le serveur, mais pour être sûr d’avoir une valeur par défaut nous allons déclarer ce setting ainsi que sa valeur par default dans son manifest.

Editez le fichier PackageInfo.xml pour ajouter :

Ainsi même si le setting n’est pas déclaré sur le serveur ni dans le App.config local, cette valeur sera par défaut égale à 5 secondes.

Vous pouvez démarrer le projet en mode debug (“F5” ou bouton “Start”) mais bien entendu il ne sera pas connecté à Constellation.

Pour débugger dans Constellation, vous trouverez une icone dans la toolbar (en en pressant Ctrl+Alt+F8) :

Vous pouvez également cliquez droit sur votre projet et dans le menu Constellation sélectionnez “Debug On Constellation” :

Si vous n’avez pas encore configuré la Constellation utilisée pour le débogage, vous devriez voir une alerte vous invitant à configurer vos accès :

Cette fois ci, votre package tourne bien en étant connecté à votre Constellation :

Lancez maintenant votre Console Constellation, vous verrez en temps réel les logs de votre package.

Sur le StateObject Explorer, vous verrez également le StateObject “DemoLong” publié par le package “MonPremierPackage”.

Notez que la sentinelle qui héberge le package est une sentinelle virtuelle nommée “Developer”.

Vous pouvez cliquer sur “View” pour voir toutes les informations à propos de ce StateObject.

Pour finir, cliquez sur “Subscribe” pour vous abonner aux mises à jour.

Publier son package dans Constellation

Nous voulons maintenant publier ce package et le déployer sur une des sentinelles de notre Constellation.

Toujours dans la toolbar “Constellation”, cliquez sur “Publish Constellation package” :

Ou depuis le menu contextuel de votre projet, sélectionnez “Publish Constellation package” :

Vous pouvez soit le publier en local puis l’uploader manuellement via la Console par exemple, soit le publier directement dans votre Constellation.

Pour cela, sélectionnez “Upload on Constellation Server”.

Sélectionnez ensuite l’adresse de votre Constellation et cliquez sur “Publish”.

Un message vous informera de la réussite de la publication. Dans le panneau “Ouput” de Visual Studio vous retrouvez également le détail de la publication :

Depuis la Console, sur la page “Package Repository” vous pourrez apercevoir votre package fraichement publié :

Pour le déployer, vous devez éditer la configuration de votre Constellation pour ajouter le package à une (ou plusieurs) sentinelle. Vous pouvez également redéfinir le setting “Interval” que nous exploitations dans notre package (bien que nous avons défini une valeur par défaut).

Vous pouvez éditer la configuration du serveur Constellation directement depuis Visual Studio en cloquant sur “Edit Constellation Server configuration” (depuis la toolbar ou via le menu contextuel).

La configuration sera automatiquement téléchargée du serveur et ouverte dans Visual Studio :

L’avantage est de pouvoir profiter de la validation du schéma XML et de l’IntelliSense de Visual Studio :

Dès que vous enregistrerez votre configuration, Visual Studio détectera les modifications et vous proposera d’uploader et de recharger la nouvelle configuration sur votre serveur Constellation :

Vous pouvez aussi éditer la configuration de votre Constellation depuis la Console. Après avoir ajouter votre package, cliquez sur “Save & Deploy” (pour informer les sentinelles des nouveaux packages) :

Vous pourrez alors voir dans les logs que le package est automatiquement téléchargé et déployé sur sa sentinelle et commence à pusher des StateObject toutes les 2 secondes comme nous l’avons indiqué dans sa configuration :

Sur la page “Packages” vous pouvez maintenant contrôler votre package, l’arrêter, le redémarrer ou le recharger (= déploiement d’une nouvelle version).

Next steps

Les bases des packages .NET
Les Settings : paramètres de configuration de vos packages
Publier des StateObjects
Exposer vos méthodes dans Constellation grâce aux MessageCallbacks
Envoyer des messages & Invoquer des méthodes
Consommer des StateObjects
Accéder au hub de contrôle depuis un package C# avec le ControlManager
Créer des Packages UI en Winform ou WPF

The post Créez votre premier package Constellation en C# appeared first on Constellation.

Les bases des packages .NET

Sebastien Warin — Mon, 21 Mar 2016 13:21:31 +0000

Fonctionnement de base

Comme nous l’avons vu dans le tutoriel précèdent, un package est une application !

Lorsque vous appelez la méthode “PackageHost.Start” vous devez impérativement transférer les arguments (args) et indiquer la classe de votre package (ici nommée “MonPackage”).

static void Main(string[] args)
{
    PackageHost.Start(args);
}

La classe d’un package doit être une classe qui implémente l’interface “IPackage”. Cette interface définit trois méthodes :

OnStart qui sera invoqué lorsque le package a démarré
OnPreShutdown : invoqué lorsque le package va s’arrêter (à ce stade votre package est toujours connecté à Constellation, vous pouvez encore pusher des StateObjects, envoyer des messages, écrire des logs sur le hub, etc..)
OnShutdown : invoqué après le OnPreShutdown et après avoir fermé les connexions (plus aucune interaction avec la Constellation possible)

Pour vous éviter de devoir implémenter ces trois méthodes, votre classe peut hériter de la classe “PackageBase”. Cette classe abstraite implémente l’interface IPackage dans des méthodes virtuelles vides.

Libre à vous d’implémenter les méthodes que vous souhaitez !

public class MonPackage : PackageBase
{
    //public override void OnStart()
    //{
    //}

    //public override void OnPreShutdown()
    //{
    //}

    //public override void OnShutdown()
    //{
    //}
}

Ecrire des logs

Pour écrire des logs depuis un package Constellation vous disposez des méthodes suivantes :

PackageHost.WriteDebug
PackageHost.WriteInfo
PackageHost.WriteWarn
PackageHost.WriteError

Chacune de ces méthodes écrivent un message qui peut être formaté avec des arguments à la manière d’un “string.Format” :

PackageHost.WriteInfo("Je suis le package nommé {0} version {1}", PackageHost.PackageName, PackageHost.PackageVersion);

Attention : bien respecter les index dans le format de votre message sous peine d’avoir une erreur.

Pour éviter cela, vous pouvez depuis C# 6.0 (intégré nativement depuis Visual Studio 2015), utiliser les « chaines interpolée » en plaçant en début de chaine un « $ » afin de pouvoir placer les arguments directement dans la chaine :

PackageHost.WriteInfo($"Je suis le package nommé {PackageHost.PackageName} version {PackageHost.PackageVersion}");

Note : la méthode WriteDebug écrit seulement dans la console (mode debug local). Les logs de type “Debug” ne sont jamais envoyés dans la Constellation.

Propriétés du PackageHost

La classe centrale “PackageHost” expose différentes propriétés pour votre package Constellation.

PackageHost.IsRunning

Il s’agit d’un booléen qui indique si votre package est démarré. Il est affecté à “true” juste avant le OnStart et passe à “false” juste avant le OnPreShutdown.

Cela vous permet de connaitre l’état de votre package et sert notamment pour interrompre des boucles :

while (PackageHost.IsRunning)
{
    // Do job
}

PackageHost.IsStandAlone

Cette propriété vous indique si votre package est démarré en “stand-alone”, c’est à dire lancé manuellement (en lançant le EXE) ou via Visual Studio (Debug on Constellation).

Si le package est démarré depuis une sentinelle Constellation, cette propriété est à “false”.

PackageHost.IsConnected

Vous indiques si le package est connecté ou non à la Constellation.

PackageHost.ConstellationHub

Retourne le proxy SignalR du hub Constellation.

PackageHost.HasControlManager

Indique si le package est connecté au hub de contrôle.

PackageHost.ControlManager

Retourne le client du hub de contrôle permettant de contrôler la Constellation. (plus d’information)

Cette propriété est nulle si votre package ne demande pas de connexion au hub de contrôle. Vous devez donc tester si le client est disponible ou non avec la propriété ci-dessus :

if (PackageHost.HasControlManager)
{
     PackageHost.ControlManager.xxxx();
}

PackageHost.Package

Retourne l’instance de votre package.

PackageHost.PackageDescriptor

Retourne l’instance du PackageDescriptor qui contient la description de vos MessagesCallbacks et StateObjects.

PackageHost.PackageName

Retourne le nom du package.

Le nom du package est défini dans le manifeste du package (PackageInfo.xml). Si aucune valeur n’est trouvée, le nom du package est le nom de l’assembly .NET du package.

PackageHost.PackageInstanceName

Retourne le nom de l’instance du package, c’est à dire le nom défini sur le serveur.

Un même package peut avoir plusieurs instances sur une même sentinelle mais avec des noms de package différents.

PackageHost.SentinelName

Retourne le nom de la sentinelle qui a démarré le package (si IsStandAlone = false).

Cette propriété est nulle si le package est démarré manuellement (en lançant le EXE) ou égale à “Developer” si lancé depuis Visual Studio.

PackageHost.PackageVersion

Retourne le numéro de version du package tel que défini dans le manifeste du package. Si il n’y a pas de manifeste, elle retourne le “PackageAssemblyVersion”.

PackageHost.PackageAssemblyVersion

Retourne le numéro de version de l’assembly du package.

PackageHost.ConstellationClientVersion

Retourne le numéro de version de la librairie Constellation utilisée par le package.

PackageHost.PackageManifest

Retourne le manifeste du package. (plus d’information)

PackageHost.Settings

Retourne les settings du packages. (plus d’information)

Connexion à Constellation

Pour savoir si votre package est connecté à Constellation, vous pouvez interroger la propriété “PackageHost.IsConnected” comme indiqué ci-dessus.

Vous avez également l’évènement “ConnectionStateChanged” qui se déclenche lorsque le statut de la connexion change :

PackageHost.ConnectionStateChanged += (s, e) =>
{
    if (PackageHost.IsConnected)
    {
        // Récupération de la connexion
        // TODO : MAJ des états ?
    }
    else
    {
        // Perte de la connexion
    }
};

Notez que lors de la première connexion cet événement n’est pas levé car Constellation n’a pas encore invoqué la méthode “OnStart” de votre package. Autrement dit le package se connecte d’abord puis “vous donnes la main”.

Donc si l’événement “ConnectionStateChanged“ est déclenché et que la propriété PackageHost.IsConnected = true, c’est qu’il s’agit forcement d’une reconnexion !

Dans ce cas, et en fonction de votre package, il est recommandé de “mettre à jour l’état” de votre package en re-pushant vos StateObjects.

Exemple :

Vous développez un package Constellation qui fait le lien vers votre système d’alarme.

Chaque zone de votre alarme est publiée dans Constellation sous forme de StateObject. Vous avez donc autant de StateObject que de zone et chacun de ces StateObjects indique l’état d’une zone de l’alarme (ouverte ou fermée).

Si pour une raison ou pour une autre, la connexion entre le package et la Constellation est rompue, l’activité sur les zones de l’alarme ne peut donc plus être mis à jours.

C’est pour cela que lorsque votre package parvient à se reconnecter il peut être nécessaire de republier tous les StateObjects sur Constellation pour être sûr d’avoir des StateObjects à jour par rapport à votre système d’alarme.

The post Les bases des packages .NET appeared first on Constellation.

Settings : paramètres de configuration de vos packages

Sebastien Warin — Wed, 16 Mar 2016 12:15:58 +0000

Chaque package peut définir des paramètres de configuration centralisés au niveau du serveur Constellation.

L’ensemble des paramètres des configurations de vos différents packages, virtuels ou non, sont donc centralisés dans un fichier unique. Une modification de valeur est automatiquement mis à jour sur le package cible.

Il y a deux types de settings :

Le “Setting Value” : il s’agit d’un couple clé/valeur défini dans des attributs XML à l’instar des d’une application .NET
Le “Setting Content” : au lieu de définir la valeur d’un paramètre dans un attribut XML, on peut la définir dans un élément XML enfant permettant d’avoir des settings renfermant du XML ou JSON

Les Settings Values

Voici par exemple des “SettingValues” déclarés dans la configuration d’un package :

Ces trois settings définissent la valeur dans l’attribut “value” (= SettingValue).

Pour récupérer la valeur du paramètre “MyStringSetting” dans votre code C#, vous pouvez utiliser la méthode “GetSettingValue” :

PackageHost.WriteInfo("My String = {0}", PackageHost.GetSettingValue("MyStringSetting"));

La méthode “GetSettingValue” vous retourne par défaut la valeur d’un setting en “string” mais vous pouvez également convertir cette valeur en précisant le type attendu :

int myIntSetting = PackageHost.GetSettingValue("MyIntSetting");
bool myBoolSetting = PackageHost.GetSettingValue("MyBoolSetting");

Les Settings Contents

Si vous avez un modèle de configuration plus compliqué qu’une série de clé/valeur vous pouvez utiliser les “Setting Contents” pour définir du XML ou JSON comme valeur de setting.

Par exemple la configuration de votre package peut définir deux autres settings, l’un contenant du XML et l’autre du JSON de cette façon :


  
    
      Tove
      Jani
      Reminder
      Don't forget me this weekend!

Voici les méthodes pour récupérer ces settings :

GetSettingValue : récupère le contenu brute de votre setting sous forme d’un string
GetSettingAsJsonObject : dé-sérialise le contenu JSON de votre setting et vous retourne un objet dynamique
GetSettingAsJsonObject : dé-sérialise le contenu JSON de votre setting et le converti dans un objet de votre type (T)
GetSettingAsXmlDocument : dé-sérialise le contenu XML de votre setting et vous retourne un XmlDocument
GetSettingAsConfigurationSection : dé-sérialise le contenu XML de votre setting sous forme d’un ConfigurationSection .NET

Par exemple, pour manipuler le setting XML on pourrait écrire :

var xml = PackageHost.GetSettingAsXmlDocument("MyXmlDocument");
PackageHost.WriteInfo("My XmlDocument Attribute = {0} , first node value = {1}", xml.ChildNodes[0].Attributes["date"].Value, xml.ChildNodes[0].FirstChild.InnerText);

Autre exemple avec le setting JSON :

dynamic json = PackageHost.GetSettingAsJsonObject("MyJsonObject");
PackageHost.WriteInfo("My JsonObject String={0}, Int={1}, Boolean={2}", json.String, json.Number, json.Boolean);

TryGetSettings

Notez que toutes ces méthodes citées ci-dessus ont un équivalent de type “TryGetSettingXXX” :

TryGetSettingAsConfigurationSection
TryGetSettingAsJsonObject
TryGetSettingAsJsonObject
TryGetSettingAsXmlDocument
TryGetSettingValue

Ces méthodes placent le résultat dans un paramètre de sortie (“out”) et vous retourne un booléen indiquant si l’opération est réussite ou non.

Par exemple :

int monParametre = 0;
if (PackageHost.TryGetSettingValue("MyIntSetting", out monParametre))
{
    PackageHost.WriteInfo("Lecture de 'MyIntSetting' en int OK. Valeur = {0}", monParametre);
}
else
{
    PackageHost.WriteError("Impossible de récupérer le setting 'MyIntSetting' en int");
}

Déclarer les settings dans le Package Manifest

Tous les settings devraient être déclarés dans le manifeste du package (fichier PackageInfo.xml).

La déclaration des settings dans le manifeste n’a pas impact dans le fonctionnement du package mais il permet de décrire la configuration du package pour que des outils tel que la Console puisse proposer une interface graphique de configuration pour chaque package. Il est donc vivement recommandé de décrire les settings de ses packages. De plus il est possible de définir des valeurs par défaut dans le manifeste.

Chaque setting déclaré dans le manifeste doit obligatoirement comporter les attributs suivants :

Name : le nom (clé) du setting
Type : le type du setting

Le type peut être :

Boolean : un booléen (true/false)
Double : un double
String : un chaine de caractère
Int32 : un entier (32 bits)
Int64 : un long (64 bits)
ConfigurationSection : un section de configuration .NET
DateTime : un DateTime
TimeSpan : une durée
XmlDocument : un document XML
JsonObject : un objet JSON (objet ou tableau)

Ensuite vous pouvez définir d’autre attribut pour décrire vos settings :

“isRequired“ : indique si le setting est obligatoire ou non (par défaut “false”)
“description” : la description du setting (texte qui sera affiché à l’utilisateur)
“defaultValue” : la valeur par défaut du setting si le setting n’est pas déclaré (ni sur le serveur, ni dans le fichier local App.config et seulement si le setting n’est pas obligatoire)
“schemaXSD” : indique le nom du fichier du schéma XSD (chemin relatif au package) que la valeur XML doit valider (seulement pour les settings de type XmlDocument ou ConfigurationSection)
“ignoreLocalValue” : si “true” alors la valeur définie dans le fichier local App.config est ignorée
“ignoreDefaultValue” : si “true” alors la valeur par défaut définie dans le manifeste est ignorée

Pour les settings XmlDocument, ConfigurationSection et JsonObject vous pouvez également ajouter une sous-section sur vos settings pour définir le contenu par défaut.

Pour plus d’information, veuillez lire l’article sur le Package Manifest.

Déclarez des settings dans votre configuration locale

Les settings d’un package sont déclarés au niveau du serveur Constellation mais vous pouvez également les déclarer dans le fichier App.config de votre package. Cela est très utile pendant la phase de développement.

Pour définir les settings dans le fichier App.config vous devez utiliser la section “constellationSettings ». Le schéma et le fonctionnement sont exactement les mêmes que pour la configuration définie sur le serveur Constellation.

Par exemple, dans le fichier App.config de votre package, on peut écrire :


  
    
    
    
      
        
          Tove
          Jani
          Reminder
          Don't forget me this weekend!

La structure est présente par défaut dans les projets Constellation créés depuis le SDK Constellation pour Visual Studio.

Si un même setting (= même clé) est déclaré à la fois sur le serveur Constellation et dans le fichier local, c’est toujours la valeur définie sur le serveur qui gagne (voir ci-dessous).

Notez également que si un setting est déclaré comme obligatoire dans le manifeste, il est automatiquement supprimé du fichier App.config lorsque vous publiez ce package depuis Visual Studio (que ce soit en local ou sur un serveur). Vous pouvez donc mettre vos “credentials” ou autre information personnel pour vos développements tout en sachant qu’ils seront supprimés lorsque vous publierez votre package.

Résolution des settings

Par défaut, la valeur d’un setting est en priorité récupérée depuis la configuration du package défini sur le serveur Constellation.

Si le setting n’existe pas sur le serveur (et qu’il n’est pas déclaré comme obligatoire dans le manifeste du package), le package va chercher la valeur du setting dans le fichier de configuration local App.config.

Si le fichier local App.config ne défini pas non plus de valeur pour ce setting ou que le manifeste demande d’ignorer cette valeur (ignoreLocalValue à true), le package va alors chercher la valeur par défaut de ce setting dans le manifeste (attribut “defaultValue” ou section”defaultContent”).

Si le manifeste du package ne défini pas de valeur par défaut pour ce setting, ou que cette valeur doit être ignorée (ignoreDefaultValue à true), la valeur du setting sera nulle.

Le processus de résolution des settings peut se résumé ainsi :

Prenons un exemple pour bien comprendre. Si votre package est déclaré sur le serveur de cette façon :

Et que le package contient dans son fichier local App.config la section suivante :

Avec dans son manifeste, la déclaration suivante :

Imaginez maintenant le code C# suivant :

PackageHost.WriteInfo("My String = {0}", PackageHost.GetSettingValue("MyStringSetting"));
PackageHost.WriteInfo("My Int = {0}", PackageHost.GetSettingValue("MyIntSetting"));

Si vous lancez le package en debug depuis Visual Studio :

My String = “Valeur locale”
My Int = 123

Les valeurs sont simplement lues depuis le fichier de configuration locale. Si maintenant vous supprimez le setting dans votre App.config, la valeur de MyIntSetting sera 1234, c’est à dire la valeur par défaut du manifest.

Maintenant si vous déployez votre package dans votre Constellation :

My String = “Valeur du serveur”
My Int = 1234

My String est bien récupéré depuis la configuration du serveur (car prioritaire), cependant “MyIntSetting” n’étant pas déclaré sur le serveur, le package va tenter de lire cette valeur depuis la configuration locale (123) mais le manifeste demande à ignorer la valeur locale (ignoreLocalValue= »true » dans le manifeste) ce qui l’amène à récupérer la valeur par défaut (defaultValue) déclaré dans le manifeste du package. Donc MyIntSetting = 1234.

Note sur le “ignoreDefaultValue”

On peut se demander quel est l’intérêt de définir une valeur par défaut tout demandant de l’ignorer (ignoreDefaultValue = true).

En fait la valeur par défaut du manifeste peut être considérée comme un “exemple”. La defaultValue ou defaultContent est affiché à titre d’exemple à l’utilisateur lors de la configuration de son package dans la Console Constellation. Cela est surtout fort utile pour les “Setting Contents”, car ça renseigne l’utilisateur la structure du XML ou du JSON du setting.

Mais une valeur d’ “exemple” ne doit pas être chargée ! De ce fait on déclare un setting avec une defaultValue/defaultContent pour l’exemple et on demande à ne jamais tenir compte de cette valeur en l’ignorant (ignoreDefaultValue = true).

Si on veut une valeur “par défaut”, on utilisera le fichier local App.config.

En clair, on peut voir les choses ainsi :

Valeur déclarée dans la configuration du package au niveau du serveur Constellation = configuration de l’utilisateur
Valeur déclarée dans la configuration locale du package (App.config) = configuration pour le développement ou valeur par défaut
Valeur déclarée dans le manifeste du package (PackagInfo.xml) = exemple de configuration ou valeur par défaut

Mise à jour dynamique

Les settings d’un package sont récupérés du serveur Constellation au démarrage du package. Il est également possible de “pusher” les settings d’un package lorsque le package est en fonctionnement.

Il y a trois façons de “pusher” les settings sur un package :

Lors du rechargement de la configuration Constellation sur le serveur
Lors d’un “UpdateSettings” sur un package en particulier via le hub contrôle
A la demande d’un package via la méthode “RequestSettings”

Le hub de contrôle (control hub) expose une méthode “reloadServerConfiguration” permettant de recharger la configuration de la Constellation au niveau du serveur. Cette méthode prend en paramètre un booléen (optionnel) indiquant si il faut ou non déployer la configuration après son rechargement sur le serveur. Par défaut ce paramètre est à “false” (la configuration est seulement rechargée).

Lorsque la configuration est déployée, le serveur Constellation informe toutes les sentinelles et tous les packages que la configuration a changé. Chaque package recevra la valeurs des settings déclarées dans la nouvelle configuration et chaque sentinelle se conformera à sa configuration (arrêt des packages supprimés et déploiement/démarrage des packages ajoutés).

Il est possible de lancer cette action depuis la Console Constellation (soit depuis la page “Packages” ou soit depuis la page “Configuration Editor« ).

L’autre possibilité, toujours sur le hub de contrôle, avec une méthode “updateSettings” permettant de pusher les settings du serveur vers un package en particulier. Vous retrouverez également cette action depuis la Console Constellation :

Enfin, le package lui-même peut faire la demande au serveur de lui renvoyer ses settings par la méthode suivante :

PackageHost.RequestSettings();

Dans tous les cas, le dictionnaire des settings de votre package (propriété PackageHost.Settings) sera mis à jour de façon de transparent (en tenant compte du processus de résolution des settings décrit ci-dessus).

Ainsi, lorsque vous appelez les méthodes GetSettingXXXX, elles vous retourneront toujours les dernières valeurs des settings. C’est pourquoi il est conseillé de ne jamais mettre en cache les valeurs des settings et de toujours invoquer les méthodes GetSettingsXXX pour tenir compte des modifications en temps réel.

Vous avez également la possibilité de vous abonnez à l’événement “PackageHost.SettingsUpdated” pour être informé de ces mises à jour et agir en conséquence :

PackageHost.SettingsUpdated += (s, e) =>
{
    PackageHost.WriteInfo("Mise à jours des settings");
    PackageHost.WriteInfo("Il y a {0} setting(s)", PackageHost.Settings.Count);
};

Les groupes de Settings

Vous pouvez grouper des settings (Content ou Value) dans des groupes au niveau du serveur et importer ces groupes dans les settings de vos packages ou dans d’autres groupes.

Par exemple, créons un groupe pour “HWMonitorSettings” qui contient le setting “Interval” :

Ainsi pour chaque instance du package “HWMonitor”, vous pouvez importer le groupe “HWMonitorSettings” afin de centraliser la configuration de ce package :

Vous pouvez importer des groupes dans des groupes sans limite.

C’est toujours la valeur du setting la plus proche du package qui gagne (surcharge).

Bien entendu, vous pouvez créer autant de groupe que vous voulez et chaque groupe peut contenir des SettingValues ou des SettingContents :


  
    
      
      
    
  
  
    
      
        
      
      
      
    
  
  
    
      
      
      
        
          
            Tove
            Jani
            Reminder
            Don't forget me this weekend!

Pour bien comprendre, imaginez le package suivant :

Ici cette instance du package “DemoPackage” contient 7 settings (sans prendre en compte les settings déclarés dans le fichier local et le manifeste) :

numberTest = 42 (défini dans les settings du package)
Demo1 = “It’s me” (défini dans les settings du package, cette valeur écrase celle des groupes importés)
Demo2 = 2015 (défini par le groupe “test2”. Cette valeur écrase la valeur du groupe “test”, car le groupe “test2” est importé APRES le groupe “test”)
MyStringSetting, MyBoolSetting, MyXmlDocument et MyJsonObject définis par le groupe “common” (groupe importé dans le groupe “test2” lui même importé sur le package “DemoPackage”).

The post Settings : paramètres de configuration de vos packages appeared first on Constellation.

Publier des StateObjects

Sebastien Warin — Fri, 18 Mar 2016 22:08:49 +0000

Publier des StateObjects

Pour publier (Push) un StateObject dans Constellation vous devez invoquer la méthode “PackageHost.PushStateObject” en précisant obligatoirement le nom du StateObject et sa valeur.

Par exemple, vous pouvez publier un StateObject avec en valeur n’importe quel type de base :

PackageHost.PushStateObject("MyString", "OK");
PackageHost.PushStateObject("MyNumber", 123);
PackageHost.PushStateObject("MyDecimal", 123.12);
PackageHost.PushStateObject("MyBoolean", true);

Vous pouvez parcourir tous les StateObjects de votre Constellation grâce au “StateObject Explorer” de la Console Constellation :

Pouvez également publier des objets avec un type anonyme :

PackageHost.PushStateObject("AnonymousObject", new { String = "test", Number = 123 });

Ou encore avec des types complexes :

PackageHost.PushStateObject("MyObject",  new MyCustomObject() { String = "test", Number = 123 });

Depuis la Console, vous pouvez analyser en détail vos StateObjects et même les suivre en temps réel :

Vous avez également la possibilité de définir des paramètres optionnels sur cette méthode pour ajouter les métadonnées de votre StateObject ou encore définir sa durée de vie.

Par exemple, ici le StateObject “ShortLife” a ici une durée de vie de 20 secondes. Au delà il sera donc considéré comme expiré si il n’est pas mis à jour après 20 secondes.

PackageHost.PushStateObject("ShortLife", "Expire in 20 secs !!!", lifetime: 20);

Ci-dessous, on publie un StateObject “Salon” en lui associant les metadatas “Id” et “Zone”.

PackageHost.PushStateObject("Salon", monObjetZoneSalon, metadatas: new Dictionary { { "Id", 42 }, { "Zone", "Salon" } });

Note : à chaque (re)démarrage de votre package, tous les StateObjects du package sont purgés de la Constellation.

Décrire les types de StateObjects

Il est recommandé de décrire les types complexes de vos StateObjects dans la Constellation pour activer l’auto-description (utilisé entre autre par les générateurs de code ou le MessageCallback Explorer de la Console).

Sur les objets personnalisés il suffit de décorer les classes de l’attribut [StateObject]. Par exemple pour reprendre l’exemple ci dessus, la classe du StateObject “MyObject” pourrait être défini ainsi :

/// 
/// Mon StateObject complexe
/// 
[StateObject]
public class MyCustomObject
{
    /// 
    /// Gets or sets the number.
    /// 
    public int Number { get; set; }
    /// 
    /// Gets or sets the string.
    /// 
    public string String { get; set; }
    /// 
    /// Gets or sets the date time.
    /// 
    public DateTime UnTypeComplexe { get; set; }
}

Deux points à retenir :

Marquer la classe de l’attribut [StateObject] pour l’inclure dans la description du package
Ajouter des commentaires de documentation XML pour décrire le StateObject et ses propriétés.

Autrement si vous être amené à publier des StateObjects d’un type dont vous n’avez pas la possibilité de modifier le code pour ajouter l’attribut [StateObject] (par exemple un type d’une libraire tierce), vous pouvez sur votre classe IPackage, ajoutez l’attribut [StateObjectKnownTypes] en définissant la liste des types de StateObjects à décrire :

[StateObjectKnownTypes(typeof(ThridParty.ComplexObject), typeof(AnotherThridParty.AnotherType))]
public class Program : PackageBase
{
}

Vous avez également la possibilité d’ajouter à tout moment la description d’un type de StateObject via les méthodes :

PackageHost.DescribeStateObjectTypes : en passant une liste de Type
PackageHost.DescribeStateObjectTypesFromAssembly : en passant une assembly (qui sera scannée à la recherche des classes marquées par l’attribut [StateObject])

Si vous ajoutez vous-même des types de StateObjects dans la description du package via les deux méthodes ci-dessus, vous devez ensuite mettre à jour la description du package par la ligne :

PackageHost.DeclarePackageDescriptor();

Supprimer des StateObjects

Vous avez deux moyens de supprimer des StateObjects :

PackageHost.PurgeStateObjects : pour supprimer les StateObjects de votre package
PackageHost.ControlManager.PurgeStateObjects : pour supprimer n’importe quel StateObject de votre Constellation en utilisant le ControlManager (nécessite une clé d’accès autorisant l’accès au hub de contrôle). Plus di’nformation ici

The post Publier des StateObjects appeared first on Constellation.

MessageCallbacks : exposez vos méthodes

Sebastien Warin — Wed, 16 Mar 2016 14:14:25 +0000

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 :

[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 :

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

    return user.User == user.Password;
}

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

    /// 
    /// Le mot de passe de l'utilisateur
    /// 
    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.

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.

Consommer des StateObjects

Sebastien Warin — Sun, 20 Mar 2016 14:18:48 +0000

Chaque package, virtuel ou non, peut publier des StateObjects dans votre Constellation. Découvrons dans cet article comment intégrer les valeurs de ces StateObjets dans votre code C#.

La base : le Request & Subscribe de StateObjects

Le hub Constellation comporte deux méthodes :

RequestStateObjects : permettant d’interroger « à un instant T » des StateObjects de votre Constellation
SubscribeStateObjects : permettant de s’abonner aux mises à jours des StateObjects de votre Constellation

Ces deux méthodes acceptent jusqu’à 4 paramètres, tous optionnels :

string sentinel = "*", string package = "*", string name = "*", string type = "*"

Vous devez définir le ou StateObjects que vous souhaitez récupérer (Request) ou suivre (Subscribe) en appliquant des filtres. Le wildcard “*” permet de tout sélectionner, c’est à dire de ne pas filtrer.

Par exemple, pour récupérer tous les StateObjects du package “MonPackage” (et peut importe le nombre d’instance du package) :

PackageHost.RequestStateObjects(package: "MonPackage");

Si vous souhaitez tous les StateObjects du package “MonPackage” qui tourne sur une sentinelle en particulier, nommée ci-dessous « MA-SENTINELLE » :

PackageHost.RequestStateObjects(sentinel:"MA-SENTINELLE", package: "MonPackage");

Pour cibler un StateObject en participer sur une instance d’un package :

PackageHost.RequestStateObjects(sentinel: "MA-SENTINELLE", package: "MonPackage", name:"MonStateObject");

Bien entendu, vous pouvez définir la combinaison que vous souhaitez !

Par exemple, récupérons tous les StateObjects de type “HWMonitor.HardwareList” dans notre Constellation :

PackageHost.RequestStateObjects(type: "HWMonitor.HardwareList");

Comme on sait que ce type de StateObject ne peut être publié que par le package “HWMonitor”, on pourrait écrire :

PackageHost.RequestStateObjects(package: "HWMonitor", type: "HWMonitor.HardwareList");

Dans les deux cas (Request ou Subscribe) les StateObjects sont reçus un par un par l’événement .NET : “PackageHost.StateObjectUpdated”.

Par exemple, déployons le package”HWMonitor” et analysons le StateObject “Hardware” via le StateObject Explorer :

On retrouve un StateObject de type “HWMonitor.HardwareList” qui contient une liste du hardware de la machine.

Dans notre package nous allons récupérer tous les StateObjects de type “HWMonitor.HardwareList” (donc autant de StateObjects que nous avons d’instance de ce package dans notre Constellation).

On pourrait écrire :

PackageHost.StateObjectUpdated += (s, e) =>
{
    PackageHost.WriteInfo("Hardware sur la machine {0}", e.StateObject.SentinelName);
    foreach (dynamic hw in e.StateObject.DynamicValue)
    {
        PackageHost.WriteInfo("{0} ({1})", hw.Name, hw.Identifier);
    }
};
PackageHost.RequestStateObjects(package: "HWMonitor", type: "HWMonitor.HardwareList");

En testant notre package dans Constellation :

Notez qu’ici nous avons utilisé la méthode « RequestStateObjects » c’est à dire que nous récupérons tous les StateObjects du package HWMonitor (quelque soit la sentinelle) de type « HWMonitor.HardwareList » au moement de l’invocation de la méthode.

Allons un peu plus long en affichant en temps réel la consommation du CPU. Cette valeur est publiée dans le StateObject “/intelcpu/0/load/0” par le package HWMonitor.

Pour suivre en temps réel la consommation du CPU des machines (sentinelles) sur lesquelles le package HWMonitor est déployé, on commence par s’abonner à ce StateObject :

PackageHost.SubscribeStateObjects(package: "HWMonitor", name: "/intelcpu/0/load/0");

Puis dans l’événement “StateObjectUpdated” il faudra différencier le traitement en fonction du StateObject reçu.

Le code final :

PackageHost.StateObjectUpdated += (s, e) =>
{
    if (e.StateObject.Name == "Hardware")
    {
        PackageHost.WriteInfo("Hardware sur la machine {0}", e.StateObject.SentinelName);
        foreach (dynamic hw in e.StateObject.DynamicValue)
        {
            PackageHost.WriteInfo("{0} ({1})", hw.Name, hw.Identifier);
        }
    }
    else if (e.StateObject.Name == "/intelcpu/0/load/0")
    {
        PackageHost.WriteInfo("CPU de {0} = {1}%", e.StateObject.SentinelName, e.StateObject.DynamicValue.Value);
    }
};
PackageHost.RequestStateObjects(package: "HWMonitor", type: "HWMonitor.HardwareList");
PackageHost.SubscribeStateObjects(package: "HWMonitor", name: "/intelcpu/0/load/0");

Notez qu’ici nous avons utilisé la méthode « SubscribeStateObjects » c’est à dire que nous nous abonnons à tous les StateObjects nommés “/intelcpu/0/load/0” du package HWMonitor (quelque soit la sentinelle). C’est un abonnement, donc à chaque modification des StateObjects respectant notre filtre, nous recevrons dans notre code les nouvelles valeurs des StateObjects.

Cependant, si les StateObjects changent peu fréquemment, nous n’obtenons rien immédiatement. C’est pourquoi il est parfois nécessaire de faire un Request suivi d’un Subscribe pour obtenir la version actuelle du/des StateObject(s) et s’abonner aux mises à jour futures.

Les StateObjectLink

Pour simplifier l’exploitation des StateObjects dans votre code, l’API Constellation introduit la notion de “StateObjectLink”.

Avec l’API.NET, il vous suffit simplement de déclarer une propriété .NET dans votre code que vous allez décorer avec l’attribut [StateObjectLink].

Votre propriété .NET peut être privée ou publique, d’instance ou statique. De plus le type de votre propriété .NET peut être :

Un type de base
Un type complexe
Un dynamic
Un StateObject
Un StateObjectNotifier
Un StateObjectCollectionNotifier

Par défaut seules les propriétés .NET de l’instance de votre package (IPackage) sont enregistrées. Si dans votre package vous instanciez des classes contenants des StateObjectsLink vous devez appeler la méthode “PackageHost.RegisterStateObjectLinks” en passant l’instance de votre classe pour l’enregistrement de ses StateObjectLinks (autrement les propriétés resteront nulles).

PackageHost.RegisterStateObjectLinks(monObjet);

Lier la valeur d’un StateObject à une propriété NET

Prenons l’exemple du StateObject “MyNumber” que vous avons publié dans cet article par la ligne :

PackageHost.PushStateObject("MyNumber", 123);

Pour qu’un autre package puisse l’inclure dans son code, on peut simplement écrire :

[StateObjectLink(Name = "MyNumber")]
public int MyNumber { get; set; }

Ici la propriété est de type “int” (car la valeur du StateObject est un int) et est liée à la valeur de ce StateObject.

Dès que le StateObject est mis à jour (PushStateObject) par le package qui la produit, votre propriété est également mise à jour de sorte que vous ayez toujours la dernière valeur du StateObject dans votre propriété.

Bien entendu la valeur du StateObject doit être compatible avec le type de la propriété liée (même type ou cast implicite possible), sinon la valeur du StateObject lié ne sera jamais affecté à votre propriété.

Vous pouvez également utiliser des types complexes. Par exemple prenons l’exemple déjà cité ci-dessus :

PackageHost.PushStateObject("MyObject",  new MyCustomObject() { String = "test", Number = 123 });

Pour créer le StateObjectLink depuis un autre package, on pourra écrire :

[StateObjectLink(Name = "MyObject")]
public MyCustomObject MyObject { get; set; }

La propriété “MyObject” sera bien du type “MyCustomObject” et sera lié au StateObject nommé “MyObject”.

Cela sous entend que votre package ait la même définition du type “MyCustomObject” : soit en recopiant la classe ou soit en partageant une assembly commune. Notez toutefois que, comme Constellation connait la description des types utilisés par les StateObjects ou MessagesCallbacks, il est possible de générer le code (lire ici).

Maintenant si le StateObject est un type anonyme ou que vous n’avez pas la définition du type dans votre code, vous pouvez utiliser le type “dynamic”.

On pourrait alors écrire :

[StateObjectLink(Name = "MyObject")]
public dynamic MyObject { get; set; }

Pour terminer reprenons notre StateObject “Hardware” publié par le package HWMonitor :

[StateObjectLink(Package = "HWMonitor", Type = "HWMonitor.HardwareList")]
private dynamic Hardware { get; set; }

Et à tout moment dans votre code pour pourrez itérer sur cette liste :

foreach (dynamic hw in this.Hardware)
{
    PackageHost.WriteInfo("{0} ({1})", hw.Name, hw.Identifier);
}

On pourrait reprendre également l’exemple du CPU mais nous aurions un problème : comment savoir quand le StateObject à été mis à jour pour afficher la nouvelle valeur ? C’est que nous verrons avec le StateObjectNotifier ci-dessous.

L’unicité des liens

Dans les exemples ci-dessus, nous lions des propriétés .NET aux StateObjects de votre Constellation en utilisant seulement leurs noms (Name). Or comme vous le savez il peut y avoir, dans votre Constellation, plusieurs packages sur plusieurs sentinelles qui publient des StateObjects avec le même nom !

De ce fait, je peux par exemple écrire :

[StateObjectLink(Package = "MonPackage", Name = "MyObject")]
public dynamic MyObject { get; set; }

Ici, je crée un lien entre cette propriété .NET et les StateObjects nommés “MyObject” et publiés par le package “MonPackage”. Mais je ne sais pas combien d’instance du package “MonPackage” je trouverai dans ma Constellation (je pourrais déployer ce package sur toutes mes sentinelles).

L’unicité ne peut se faire qu’avec le triplet : Nom de la sentinelle + Nom du package + Nom du StateObject.

[StateObjectLink(Sentinel = "MON-PC", Package = "MonPackage", Name = "MyObject")]
public dynamic MyObject { get; set; }

Dans ce dernier cas j’ai la garantie de lier cette propriété .NET à un et un seul StateObject : celui nommé “MyObject” publié par le package “MonPackage” et déployé sur la sentinelle “MON-PC”.

Dans le cas où votre lien correspond à plusieurs StateObjects, chaque mise à jours de l’un d’entre eux est affectée à la propriété.

Ainsi si vous avez un package nommé “MonPackage” qui tourne sur deux sentinelles (disons “PC1” et “PC2”), votre propriété “MyObject” définie ci-dessous sera tantôt liée à la valeur du StateObject publié par le package sur PC1 tantôt sur l’instance de PC2.

[StateObjectLink(Package = "MonPackage", Name = "MyObject")]
public dynamic MyObject { get; set; }

Soyez donc vigilant aux liens que vous créez, ou sinon utilisez les StateObjectCollectionNotifier comme nous le verrons dans la suite de cet article.

Lier le StateObject entier à une propriété .NET

Jusqu’à présent nous avons lier des propriétés .NET avec les valeurs de StateObjects. Une fois la liaison établie, vous pouvez utiliser ces propriétés pour accéder à la valeur des StateObjects mais non au StateObject lui même.

Le StateObject contient à la fois la valeur du StateObject mais également les propriétés du StateObject comme son nom, le couple sentinelle/package qui l’a publié, sa date de publication, sa durée de vie (lifetime), son type ou encore des métadonnées (dictionnaire de string/object).

Pour cela, il suffit simplement de créer une propriété de type “StateObject”.

Par exemple pour le StateObject “Hardware” du package “HWMonitor” de la sentinelle “MON-PC” (pour n’avoir qu’une seule valeur), on peut écrire :

[StateObjectLink("MON-PC", "HWMonitor", "Hardware")]
private StateObject Hardware { get; set; }

Vous aurez ensuite accès aux différentes propriétés de votre StateObject :

La valeur du StateObject peut être obtenue par la propriété “Value” ou “DynamicValue”.

La propriété “DynamicValue” retourne la “Value” en tant qu’objet dynamique. Dans le cas d’un objet complexe, la “Value” sera de type JObject ou JArray.

Il est donc conseillé de travailler directement avec la “DynamicValue” pour résoudre dynamiquement la valeur de votre StateObject.

Vous disposez également d’une méthode GetValue (ou son équivalent TryGetValue) qui se chargera de convertir votre valeur de StateObject en T .

StateObjectNotifier : être notifié des mises à jour des StateObjects liés

Jusqu’à présent nous lions des propriétés .NET avec la valeur d’un StateObject ou le StateObject lui même.

Dans les deux cas, vous pouvez accéder à tout moment à la dernière version de votre StateObject (ou sa valeur) publié dans votre Constellation car un StateObjectLink réalise implicitement un RequestStateObjects à l’initialisation de la propriété puis s’abonne aux StateObjects (SubscribeStateObject) pour mettre à jour en temps réel votre propriété dès que le ou les StateObjects liés sont mis à jour.

Seulement vous ne savez pas “quand” vos StateObject liés sont mis à jour, autrement dit quand est-ce que vos propriétés .NET sont mises à jour.

Pour cela il existe les StateObjectNotifiers. Le principe est simple, vous devez simplement créer une propriété liés de type StateObjectNotifier.

Reprenons le StateObject du CPU publié par le package HWMonitor sur “MON-PC” :

[StateObjectLink("MON-PC", "HWMonitor", "/intelcpu/0/load/0")]
private StateObjectNotifier CPU { get; set; }

La classe StateObjectNotifier un container de StateObject. Elle comporte une propriété “Value” dans laquelle est contenu le StateObject.

StateObject stateObjectActuel = this.CPU.Value;

On peut donc afficher la consommation à instant T :

PackageHost.WriteInfo("CPU = {0}%", this.CPU.Value.DynamicValue.Value);

Pour détailler :

this (l’instance courante)
.CPU (le StateObjectNofitier lié au StateObject de notre CPU)
.Value (l’objet StateObject en question)
.DynamicValue (la valeur du StateObject sous forme dynamique)
.Value (la propriété de l’objet publié par le package HWMonitor)

Notez que le StateObjectNotifier comporte une propriété “DynamicValue” qui retourne la “DynamicValue” du StateObject (en clair : StateObjectNotifier.DynamicValue = StateObjectNotifier.Value.DynamicValue).

On peut donc simplifier le code par :

PackageHost.WriteInfo("CPU = {0}%", this.CPU.DynamicValue.Value);

Lorsque le (ou les) StateObjets liés sont mis à jour, l’instance du StateObjectNotifier reste inchangée, c’est seulement sa propriété Value qui est mis à jour. De ce fait il est possible de s’abonner à des événements sur un StateObjectNotifier.

A ce sujet, le StateObjectNotifier implémente l’interface bien connue en .NET et notamment dans le monde WPF : “INotifyPropertyChanged”.

De ce fait, un StateObjectNotifier comporte un événement “PropertyChanged” qui vous informera lorsque le StateObject change.

this.CPU.PropertyChanged += (s, e) =>
{
    PackageHost.WriteInfo("Le StateObject a été mis à jour");
    PackageHost.WriteInfo("CPU = {0}%", this.CPU.DynamicValue.Value);
};

Très pratique notamment pour rafraichir une interface graphique WPF (binding WPF).

De plus le StateObjectNotifier comporte un 2ème événement qui se déclenche lui aussi à la mise à jour du StateObject : le “ValueChanged”.

La différence avec le PropertyChanged réside dans l’EventArgs passé lorsque l’événement se déclenche :

Le “StateObjectChangedEventArgs” fourni trois propriétés :

NewState : la nouvelle version du StateObject
OldState : l’ancienne version du StateObject
IsNew : un booléen qui indique si c’est un “nouveau” StateObject (c’est à dire que OldState est null)

On peut donc comparer l’évolution du StateObject

this.CPU.ValueChanged += (s, e) =>
{
    if (e.IsNew)
    {
         PackageHost.WriteInfo("CPU = {0}%", e.NewState.DynamicValue.Value);
    }
    else
    {
         double difference = (double)e.NewState.DynamicValue.Value - (double)e.OldState.DynamicValue.Value;
         PackageHost.WriteInfo("CPU = {0}% - TENDANDE: ", e.NewState.DynamicValue.Value, difference > 0 ? "A LA HAUSSE" : "A LA BAISSE");
    }
};

StateObjectLink et Notifier personnalisés

Notez que vous pouvez créer vos propres attributs “StateObjectLink” personnalisés en héritant de la classe “StateObjectLinkAttribute”.

De la même façon vous pouvez également créer vos propres StateObjectNotifier en créant simplement une classe qui hérite de “StateObjectNotifier”.

StateObjectCollectionNotifier : collection de StateObjectNotifier

Comme nous l’avons vu plus haut, si un StateObjectLink peut lier plusieurs StateObjects dans la même propriété .NET. Chaque mise à jour d’un des StateObjects “remplace” le précèdent !

Pour pouvoir lier plusieurs StateObjects dans une seule propriété .NET, nous pouvons utiliser les StateObjectCollectionNotifiers. La classe StateObjectCollectionNotifier est une ObservableCollection de StateObjectNotifier.

Prenons cet exemple :

[StateObjectLink("HWMonitor", "/intelcpu/0/load/0")]
public StateObjectCollectionNotifier CPUs { get; set; }

Nous utilisons le constructeur du StateObjectLink où le 1er argument est le nom du package et le 2ème le nom du StateObject.

Pour faciliter la compréhension, on peut également utiliser les paramètres nommés :

[StateObjectLink(Package = "HWMonitor", Name = "/intelcpu/0/load/0")]
public StateObjectCollectionNotifier CPUs { get; set; }

Nous créons donc un lien vers le StateObjects “/intelcpu/0/load/0” du package HWMonitor (celui qui correspond à la consommation du CPU).

On aura donc un StateObject par sentinelle où ce package est déployé.

Par exemple, dans ma Constellation on trouve 9 StateObjects qui correspond, un par machine (sentinelle) :

Comme il s’agit d’une collection de StateObjectNotifier, vous pouvez itérer pour chaque StateObject afin d’afficher par exemple le CPU de chaque sentinelle où le package “HWMonitor” est déployé :

foreach (StateObjectNotifier stateobject in this.CPUs)
{
     PackageHost.WriteInfo("CPU sur {0} = {1}%", stateobject.Value.SentinelName, stateobject.DynamicValue.Value);
}

Tout comme le StateObjectNotifier, la classe StateObjectCollectionNotifier comporte aussi l’évènement ValueChanged :

this.CPUs.ValueChanged += (s, e) =>
{
     PackageHost.WriteInfo("CPU sur {0} = {1}%", e.NewState.SentinelName, e.NewState.DynamicValue.Value);
};

Générer du code

Le principe est le même que la génération de code pour les MessageCallbacks.

Ouvrez le générateur de code (clic-droit sur votre projet dans Visual Studio > Constellation > Generate Code) et sélectionnez votre Constellation puis cliquez sur “Discover”. Sélectionnez ensuite les packages que vous souhaitez ajouter dans votre code et cliquez sur “Generate”.

Comme pour les MessageCallbacks, vous devez ajouter le namespace correspondant aux “StateObjects” du package que vous souhaitez manipuler.

Par exemple pour inclure les StateObjects du package “MonPremierPackage” :

using ConstellationPackageConsole1.MonPremierPackage.StateObjects;

Ensuite créez votre propriété .NET liée à un StateObject mais en utilisant le StateObjectLink généré par package.

Exemple, pour les StateObjects du package “MonPremierPackage”, vous avez la classe “MonPremierPackageStateObjectLink”.

Inutile de définir le “PackageName” sur ce StateObjectLink par il est nativement fixé par cet attribut personnalisé.

Pour le nom du StateObject, vous pouvez utiliser l’énumération MonPremierPackageStateObjectNames générée par le générateur de code :

Par exemple, pour lier notre propriété “MonObject” au StateObject “MyObject” publié par le “MonPremierPackage” (revoir l’exemple ici), on peut écrire :

[MonPremierPackageStateObjectLink(MonPremierPackageStateObjectNames.MyObject)]
public StateObjectNotifier MonObject { get; set; }

Ensuite, sur chaque StateObject ou StateObjectNotifier, vous trouverez des méthodes d’extension permettant de convertir la valeur du StateObject dans le type généré dans votre code à partir de la description du package :

Par exemple, pour convertir votre StateObjectNotifier en “MyCustomObject”, le type du StateObject défini dans le package “MonPremierPackage” :

MyCustomObject myObject = this.MonObject.AsMonPremierPackageMyCustomObject();

Chaque type de StateObject décrit dans la Constellation est reproduit par le générateur de code dans votre projet.

Vous retrouvez alors toutes les propriétés du StateObject proprement typées et documentées :

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

The post Consommer des StateObjects appeared first on Constellation.

Envoyer des messages & Invoquer des MessageCallbacks

Sebastien Warin — Wed, 16 Mar 2016 16:41:17 +0000

Avant de suivre la lecture de cet article vous devez avoir compris les concepts de base des MessageCallbacks.

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((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 reponse = PackageHost.CreateMessageProxy("MonPremierPackage").Logon(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(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(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 reponse = PackageHost.CreateMessageProxy("MonPremierPackage").Logon(new { User = "seb", Password = "seb" });

Le proxy dynamique nous retourne une ”Task”, 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 reponse = PackageHost.CreateMessageProxy("MonPremierPackage").Logon(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 reponse = PackageHost.CreateMessageProxy("MonPremierPackage").Logon(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(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 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 task = PackageHost.CreateMessageProxy("MonPremierPackage").Logon(new { User = "seb", Password = "seb" });
Task logonTask = task.ContinueWith(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 reponse = PackageHost.CreateMessageProxy("ConstellationPackageConsole1").Logon(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 reponse = PackageHost.CreateMessageProxy("ConstellationPackageConsole1").Logon(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 reponse = PackageHost.CreateMessageProxy("ConstellationPackageConsole1").Logon(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.

Persistance de données dans un package

Sebastien Warin — Mon, 21 Mar 2016 15:39:53 +0000

Certains de vos packages peuvent avoir besoin d’enregistrer/persister des données et vous devez savoir qu’à chaque mise à jour d’un package par sa sentinelle, l’ensemble du package est supprimé avant d’être redéployé.

Il existe deux possibilités pour persister les données :

Utiliser un stockage “hors Constellation”
Utiliser les StateObjects

Stocker en dehors de Constellation

Comme vous le savez, un package n’est ni plus ni moins qu’une application.

Vous pouvez donc utiliser n’importe quel système de stockage :

File System
Base de donnée en tout genre
Web service
Etc …

Libre à vous de stoker vos données où bon vous sembles mais attention si vous souhaitez diffuser votre package, vous ajoutez des prérequis pour l’installation de votre package.

Note sur le File System

Vous pouvez bien sûr stocker des données dans des fichiers. Par défaut le “CurrentDirectory” du package est son répertoire de déploiement. Prenez garde toutefois car à chaque déploiement du package par la sentinelle ce répertoire est vidé.

Vous devez donc utiliser un répertoire “externe” qu’on définira par un setting.

SerializationHelper

Notez que la librairie Constellation met à disposition la classe “SerializationHelper” dans le namespace “Constellation.Utils” permettant de sérialiser et dé-sérialiser facilement des objets en JSON ou en XML.

Constellation.Utils.SerializationHelper.SerializeToFile(new MyCustomObject() { Number = 42, String = "Demo" }, PackageHost.GetSettingValue("MyData.json"));
MyCustomObject myData = Constellation.Utils.SerializationHelper.DeserializeFromFile(PackageHost.GetSettingValue("MyData.json"));

Vous disposez des méthodes :

SerializeToFile et DeserializeFromFile pour sérialiser/dé-sérialiser vers/depuis un fichier
SerializeToString et DeserializeFromString pour sérialiser/dé-sérialiser vers/depuis un string

Par défaut c’est le format JSON qui est utilisé mais vous pouvez définir le DataContractSerialiser (format XML) dans les paramètres de la méthode.

Utiliser les StateObjects comme stockage

Le principe est d’utiliser les StateObjects comme stockage, très utile pour sauvegarder/restaurer l’état d’un package.

Chaque package peut publier des StateObjects que ce soit de simple valeur ou de véritable objet complexe. A chaque (re)démarrage de votre package, tous les StateObjects du package sont purgés de la Constellation mais cependant vous avez la possibilité de les récupérer dans votre code avant cette purge.

Pour cela vous devez ajouter dans le manifeste du package (PackageInfo.xml) l’attribut “RequestLastStateObjectsOnStart” à true.

Ensuite dans votre code, vous devez le plus tôt possible dans le “OnStart” vous abonnez à l’événement “LastStateObjectsReceived“.

Cet événement sera levé lorsque votre package recevra ses anciens StateObjects du serveur avant d’être purgés. L’argument passé dans l’événement contient une liste des StateObjects avant purge.

PackageHost.LastStateObjectsReceived += (s, e) =>
{
    PackageHost.WriteInfo("Reception de mes anciens StateObjects au nombre de {0}", e.StateObjects.Count);
};

Vous pouvez “bêtement” re-pusher l’ensemble des StateObjects sans aucune modification :

PackageHost.LastStateObjectsReceived += (s, e) =>
{
    foreach (StateObject so in e.StateObjects)
    {
        // Re-Pusher “bêtement” les StateObjects
        PackageHost.PushStateObject(so.Name, so.DynamicValue, so.Type, so.Metadatas, so.Lifetime);
    }
};

Grace à ce mécanisme, vos packages peuvent conserver des StateObject sur “leur état”.

Par exemple, imaginez un package “Brain” qui pilote l’allumage automatique des éclairages d’un jardin.

Ce package déclare un StateObjectLink vers un StateObject qui indique la luminosité extérieure. Si la valeur franchie un certain seuil, le package décide d’allumer ou éteindre les éclairages en envoyant un message pour déclencher un MessageCallback du package pilotant les éclairages.

Imaginez maintenant que suite à l’allumage automatique des éclairages par votre package vous décidez de les éteindre manuellement. Puis, quelques instants plus tard, pour diverses raisons vous devez redémarrer (ou mettre à jour) votre package “Brain”. Vos éclairages risquent de se rallumer car votre “Brain” n’a pas mémorisé qu’il a déjà réalisé cette action !

Pour ce genre de problématique, il est intéressant de stocker ces variables dans une classe d’état et de publier cette classe dans un StateObject qu’on pourra nommer “State”. Lorsque notre package redémarre, on demandera à Constellation de nous renvoyer les derniers StateObjects.

Cela nous permettra de récupérer le dernier état de notre package avant son redémarrage.

Par exemple, vous pouvez définir une classe d’état de la façon suivante :

public class CurrentState
{
    public DateTime OuvertureVolet { get; set; }

    public DateTime FemertureVolet { get; set; }

    public DateTime OuvertureLumiereJardin { get; set; } 

    // etc....

    public const string STATEOBJECT_NAME = "CurrentState";

    private static CurrentState current;

    public static CurrentState Current
    {
        get { return current; }
    }

    public static void Load(StateObject stateObject = null)
    {
        if (stateObject != null)
        {
            PackageHost.WriteInfo("Restoring state from {0}", stateObject.LastUpdate);
            current = stateObject.GetValue();
        }
        else
        {
            PackageHost.WriteInfo("Creating new state");
            current = new CurrentState();
        }
        current.Save();
    }

    public void Save()
    {
        PackageHost.WriteInfo("Saving current state");
        PackageHost.PushStateObject(STATEOBJECT_NAME, current);
    }
}

Sans oublier d’ajouter un handler pour la restauration de l’état précèdent :

PackageHost.LastStateObjectsReceived += (s, e) =>
{
    if (e.StateObjects != null)
    {
        PackageHost.WriteInfo("Received old StateObjects (Count:{0})", e.StateObjects.Count);
        CurrentState.Load(e.StateObjects.FirstOrDefault(so => so.Name == CurrentState.STATEOBJECT_NAME));
    }
};

De cette façon vous pouvez à tout moment accéder à votre variable via votre classe statique “State.Current” et dès que vous changez une valeur, invoquez la méthode Save(), pour re-pusher votre “State” comme StateObject de votre package :

if (DateTime.Now.Date != CurrentState.Current.FemertureVoletSalon.Date && ** Luminosite < seuil ****)
{
   // Fermer le volet ici !!
   CurrentState.Current.FemertureVoletSalon = DateTime.Now;
   CurrentState.Current.Save();
}

The post Persistance de données dans un package appeared first on Constellation.

Accéder au hub de contrôle avec le ControlManager

Sebastien Warin — Mon, 21 Mar 2016 10:24:49 +0000

Le hub de contrôle permet d’accéder à différentes fonctions de pilotage de votre Constellation.

Voyons en détail comment contrôler votre Constellation depuis un package C#/.NET.

Accéder au hub de contrôle

Tout d’abord il faut déclarer que votre package souhaite un accès au hub de contrôle. Pour cela vous devez ajouter l’attribut “EnableControlHub” à true dans le manifeste de votre package (fichier PackageInfo.xml).

Ensuite, il faut que votre package se connecte à votre Constellation avec une “Access Key” qui possède l’autorisation d’accès au hub de contrôle.

Il faut ajouter l’attribut “enableControlHub” à true sur un de vos credentials et affecter ce credential à votre package :

Ainsi votre package pourra accéder au hub de contrôle de contrôle. Vous devriez d’ailleurs toujours tester la propriété “HasControlManager” pour gérer les erreurs où l’accès au hub de contrôle n’est possible.

if (PackageHost.HasControlManager)
{
    PackageHost.WriteInfo("ControlHub OK");
}
else
{
    PackageHost.WriteError("ControlHub access denied !");
}

Suivre les sentinelles et leurs statuts

Il y a deux manières d’obtenir la liste des sentinelles enregistrées dans votre Constellation :

RequestSentinelsList : vous retourne la liste des sentinelles en une seule fois par l’événement “SentinelsListUpdated”
RequestSentinelUpdates : vous retourne l’état de chaque sentinelle dans l’événement “SentinelUpdated” (cet événement est levé pour chaque sentinelle)

En principe pour récupérer la liste des sentinelles de votre Constellation, vous utiliserez toujours la première méthode.

Par exemple :

PackageHost.ControlManager.SentinelsListUpdated += (s, e) =>
{
    PackageHost.WriteInfo("Il y a {0} sentinelle(s)", e.Sentinels.Count);
    foreach (SentinelInfo sentinel in e.Sentinels)
    {
        PackageHost.WriteInfo("Sentinelle '{0}' (Plateforme: {1}) => IsConnected = {2}",
            sentinel.Description.SentinelName,
            sentinel.Description.Platform,
            sentinel.IsConnected);
    }
};
PackageHost.ControlManager.RequestSentinelsList();

Vous pouvez également vous abonner en temps réel aux mises à jour des sentinelles de votre Constellation.

Pour cela il faut activer la réception des mises à jour :

PackageHost.ControlManager.ReceiveSentinelUpdates = true;

Puis attacher un handler sur l’événement “SentinelUpdated” qui se produit à chaque mise à jour d’une sentinelle :

PackageHost.ControlManager.SentinelUpdated += (s, e) =>
{
    PackageHost.WriteInfo("Sentinelle '{0}' (Plateforme: {1}) => IsConnected = {2}",
        e.Sentinel.Description.SentinelName,
        e.Sentinel.Description.Platform,
        e.Sentinel.IsConnected);
};

Superviser les packages

Récupérer les packages d’une sentinelle

Pour récupérer la liste des packages qui sont déployés sur une sentinelle vous devez attacher un handler sur l’événement “PackagesListUpdated” et appeler la méthode “RequestPackagesList” en spécifiant le nom de la sentinelle.

Pour exemple :

PackageHost.ControlManager.PackagesListUpdated += (s, e) =>
{
    PackageHost.WriteInfo("Il y a {0} package(s) sur la sentinelle {1}", e.Packages.Count, e.SentinelName);
};
PackageHost.ControlManager.RequestPackagesList("MA-SENTINELLE");

Chaque “PackageInfo” contient différentes informations sur l’instance du package (description du package, état du package, état de la connexion, version du package, etc…) :

foreach (PackageInfo package in e.Packages)
{
    PackageHost.WriteInfo("Package '{0}' - Etat = {1}", package.Package.Name, package.State);
}

Suivre l’état des packages

Vous pouvez aussi vous abonnez aux mises à jour des états des packages :

PackageHost.ControlManager.ReceivePackageState = true;

Vous pourrez ensuite être notifier de tout changement d’état de vos packages dans votre Constellation :

PackageHost.ControlManager.PackageStateUpdated += (s, e) =>
{
    PackageHost.WriteInfo("Le package '{0}' est maintenant dans l'état {1}", e.PackageName, e.State);
};

Suivre la consommation des packages

Vous pouvez aussi récupérer la consommation des ressources (CPU et RAM) de vos packages :

PackageHost.ControlManager.ReceivePackageUsage = true;

Par exemple, on pourrait écrire un warning si un package consomme plus de 50% du CPU :

PackageHost.ControlManager.PackageUsageUpdated += (s, e) =>
{
    if (e.CPU > 50) // Package consommant plus de 50% du CPU à un instant T
    {
        PackageHost.WriteWarn("Le package {0} consomme maintenant plus de 50% !!! CPU={1}% RAM={2}ko",
            e.PackageName, e.CPU, e.RAM / 1024);
    }
};

Contrôler les packages

Vous pouvez démarrer un package sur une sentinelle avec la méthode “StartPackage” :

// Démrrage du package "MonPremierPackage" sur la sentinelle "MON-PC"
PackageHost.ControlManager.StartPackage("MON-PC", "MonPremierPackage");

Ou encore l’arrêter avec la méthode “StopPackage” :

// Arret du package "MonPremierPackage" sur la sentinelle "MON-PC"
PackageHost.ControlManager.StopPackage("MON-PC", "MonPremierPackage");

Pour redémarrer (Stop puis Start) un package sur une sentinelle donnée, utilisez la méthode “RestartPackage” :

// Redémarrage du package "MonPremierPackage" sur la sentinelle "MON-PC"
PackageHost.ControlManager.RestartPackage("MON-PC", "MonPremierPackage");

Enfin pour mettre à jour un package, utilisez la méthode “ReloadPackage”.

Un “reload” stoppe le package, ordonne à la sentinelle de re-télécharger le package sur le serveur, le déploie en local avant de le démarrer.

// Mise à jour du package "MonPremierPackage" sur la sentinelle "MON-PC"
PackageHost.ControlManager.ReloadPackage("MON-PC", "MonPremierPackage");

Accéder aux logs en temps réel

Pour récupérer les logs produits par vos sentinelles et packages dans votre Constellation, activez la propriété suivante :

PackageHost.ControlManager.ReceivePackageLog = true;

Il suffit ensuite d’attacher handler sur l’événement “LogEntryReceived “.

Vous recevrez en paramètre un objet “LogEntry” qui contient toutes les informations sur un log (le message, la date, le couple Sentinelle/Package à l’origine du log et la sévérité du message).

Par exemple :

PackageHost.ControlManager.LogEntryReceived += (s, e) =>
{
    if (e.LogEntry.PackageName != PackageHost.PackageInstanceName) // Ne pas prendre les logs de ce package pour éviter la boucle ;)
    {
        // On log des logs, juste pour l'exemple ;)
        PackageHost.WriteInfo("Je reçois un log daté du {0} du package {1} sur la sentinelle {2} de type {3}." +
            "Message = {4}",
            e.LogEntry.Date.ToString(),
            e.LogEntry.SentinelName,
            e.LogEntry.PackageName,
            e.LogEntry.Level,
            e.LogEntry.Message);
    }
};

Notez qu’ici on logue dans Constellation (“WriteInfo”) les logs des autres packages (d’où le ). Ca n’a pas de sens, c’est juste pour l’exemple !

Récupérer la description des packages

Comme vous le savez, tous les MessageCallbacks ainsi que les types personnalisés utilisés en entrée ou en sortie sont décrits dans un PackageDescriptor tout comme les types personnalisés des StateObjects.

En vous connectant au hub de contrôle vous pouvez récupérer le PackageDescriptor de chaque package. Par exemple :

PackageHost.ControlManager.PackageDescriptorUpdated += (s, e) =>
{
    PackageHost.WriteInfo("Pour le package {0}, il y a {1} MessageCallback(s) associés à " +
                         "{2} type(s) ainsi que {3} type(s) de StateObject",
        e.PackageName,
        e.Descriptor.MessageCallbacks.Count,
        e.Descriptor.MessageCallbackTypes.Count,
        e.Descriptor.StateObjectTypes.Count);
};
PackageHost.ControlManager.RequestPackageDescriptor("MonPremierPackage");

Purger les StateObjects

Pour supprimer tous les StateObjects d’un package déployé une sentinelle :

PackageHost.ControlManager.PurgeStateObjects("MON-PC", "MonPremierPackage");

Vous pouvez aussi spécifier le nom du StateObject, pour supprimer un StateObject en particulier (identifié par son nom) :

PackageHost.ControlManager.PurgeStateObjects("MON-PC", "MonPremierPackage", "Demo");

Ou encore, tous les StateObjects d’un type particulier d’une instance de package :

PackageHost.ControlManager.PurgeStateObjects("MON-PC", "MonPremierPackage", type:"TypeDemo");

Recharger la configuration

Vous pouvez recharger et déployer la configuration Constellation en invoquant la méthode :

PackageHost.ControlManager.ReloadServerConfiguration();

Vous pouvez également passer un booléen pour indiquer si il faut déployer la configuration (c’est à dire pousser la configuration sur chaque sentinelle et package). Par défaut, la valeur est à “true” (la configuration est déployée).

Autrement :

PackageHost.ControlManager.ReloadServerConfiguration(false);

The post Accéder au hub de contrôle avec le ControlManager appeared first on Constellation.

Créer des packages UI en Winform ou WPF

Sebastien Warin — Tue, 22 Mar 2016 16:12:30 +0000

Vous pouvez créer des applications graphiques et les déployer sur vos sentinelles UI grâce à Constellation.

Chaque package UI pourra invoquer ou exposer des MessageCallbacks, consommer ou produire des StateObjects, etc…

Hello World WPF

Dans Visual Studio, vous créez un package WPF :

Le template est une application WPF classique :

Le IPackage de ce package est la classe “App” (App.xaml.cs). Ce package lance la fenêtre MainWindow au démarrage (méthode “OnStart”).

La “MainWindow” est une Window WPF classique à l’exception que dans le constructeur, on enregistre automatiquement les [StateObjectLink] et les [MessageCallback] de la classe. De plus on renvoie la description du package (dans le cas où vous avez ajoutez des MessageCallbacks).

public partial class MainWindow : Window
{
    public MainWindow()
    {
        PackageHost.RegisterStateObjectLinks(this);
        PackageHost.RegisterMessageCallbacks(this);
        PackageHost.DeclarePackageDescriptor();
        InitializeComponent();
    }

    private void Window_Loaded(object sender, RoutedEventArgs e)
    {
        this.Title = string.Format("IsRunning: {0} - IsConnected: {1} - IsStandAlone: {2}", PackageHost.IsRunning, PackageHost.IsConnected, PackageHost.IsStandAlone);
        PackageHost.WriteInfo("I'm running !");
    }
}

Au chargement de la fenêtre on logge un message dans Constellation et on affiche quelques propriété sur l’état du package dans le titre de cette fenêtre !

Ajoutons un simple label “Hello World” au centre de notre fenêtre :

Le code XAML sera donc:

Pour tester notre package en debug sans être connecté à Constellation : “F5”

Vous noterez que les WriteLog Constellation sont toujours afficher dans la fenêtre de sortie de Visual Studio.

Maintenant pour lançons le debug de notre package dans Visual Studio tout en le connectant à Constellation (raccourci Ctrl+Alt+F8)

Invoquer des MessageCallbacks

Vous pouvez invoquer ou exposer des MessageCallbacks comme n’importe quel package connecté dans votre Constellation.

Pour exposer des MessageCallbacks (des méthodes NET), il suffit d’ajouter l’attribut [MessageCallback] sur vos méthodes.

Pour invoquer des MessageCallbacks, il faut créer un scope et envoyer le message. Grace au proxy dynamique, vous pouvez invoquer un MessageCallback comme vous invoquerez une méthode .NET.

Dans cet exemple nous allons invoquer des MessageCallbacks des packages WindowsControl et GoogleTraffic. Vous pouvez suivre le guide ici pour déployer ces deux packages.

En vous rendant sur la page “MessageCallbacks Explorer” de la Console, vous pouvez explorer les MC exposés par les packages.

Par exemple, le package WindowsControl expose plusieurs MessageCallbacks pour arrêter, redémarrer, mettre en veille ou verrouiller l’ordinateur (= la sentinelle) sur lequel le package est déployé.

Le package GoogleTraffic expose un MessageCallback “GetRoute” pour calculer le temps de route en spécifiant un point de départ et d’arrivée. Ce MessageCallback est une saga pour vous retourner la réponse.

Pour simplifier le développement et éviter de travailler avec des types dynamiques, nous allons auto-générer le code.

Cliquez sur le bouton “Generate Code” :

Sélectionnez votre Constellation, cliquez sur “Discover” et sélectionnez les packages que vous souhaitez ajouter dans le code généré puis cliquez sur “Generate” :

Editez le code de la MainWindow (MainWindow.xaml.cs) pour ajouter le code généré des MessageCallbacks pour les packages GoogleTraffic et WindowsControl :

using MonPackageWPF.GoogleTraffic.MessageCallbacks;
using MonPackageWPF.WindowsControl.MessageCallbacks;

Dans la vue XAML, ajoutons deux boutons : l’un pour mettre en veille et l’autre pour faire un test d’itinéraire :

Pour le premier bouton, nous allons sélectionner l’instance du package “WindowsControl” sur la sentinelle “PO_SEB” pour créer un scope afin d’invoquer le MessageCallback “Sleep” :

private void btSleep_Click(object sender, RoutedEventArgs e)
{
    MyConstellation.PackageInstances.PO_SEB_WindowsControl.CreateWindowsControlScope().Sleep();
}

Prenez garde à créer un scope sur une instance (sentinelle + package) car sinon, si vous créez un scope sur le package “WindowsControl”, toutes les sentinelles hébergeant ce package se mettront en veille !

Pour le deuxième bouton, nous allons demander les différentes routes pour un “Lille-Paris”. Comme il s’agit d’une saga (message avec réponse) nous allons l’invoquer en “async/await” et afficher dans le label la meilleure route :

private async void btTestRoute_Click(object sender, RoutedEventArgs e)
{
    label.Content = "Calcul en cours ...";
    var route = await MyConstellation.Packages.GoogleTraffic.CreateGoogleTrafficScope().GetRoutes("lille", "paris");
    var bestRoute = route.OrderBy(r => r.TimeWithTraffic).FirstOrDefault();
    label.Content = $"{bestRoute.Name}\nDistance:{bestRoute.DistanceInKm}km\nTemps : {bestRoute.TimeWithTraffic}";
}

Lancer le debug dans Constellation : (ou Ctrl+Alt+F8).

Premier test, en cliquant sur Sleep, vous allez envoyer un message pour invoquer le MessageCallback “Sleep” du package “WindowsControl” sur la sentinelle ici nommée “PO-SEB”. Ainsi le Windows “PO-SEB” se mettra instantanément en veille !

Deuxième test, pour invoquer le MessageCallback “GetRoutes” du package GoogleTraffic :

Consommer des StateObjects dans votre vue XAML

Assurez-vous d’avoir dans votre Constellation au moins un package “HWMonitor” déployé sur une sentinelle. Au besoin, vous pouvez suivre ce guide ici.

Pour comprendre en détail, la consommation des StateObjects dans vos packages n’hésitez pas à relire cet article.

Par exemple, pour afficher en temps réel la consommation CPU (StateObject nommé “/intelcpu/0/load/0”) mesurée par le package HWMonitor sur sa sentinelle (ici “PO-SEB”), ajoutons un StateObjectLink :

[StateObjectLink("PO-SEB", "HWMonitor", "/intelcpu/0/load/0")]
public StateObjectNotifier CPU { get; set; }

Vous pouvez également générer du code en sélectionnant le package HWMonitor. Vous pourrez ensuite ajouter un “using” vers les StateObjects de ce package :

using MonPackageWPF.HWMonitor.StateObjects;

Cela vous permettra d’utiliser un le “HWMonitorStateObjectLink” avec des énumérations générées pour vos sentinelles et nom de StateObjects :

[HWMonitorStateObjectLink(MyConstellation.Sentinels.PO_SEB, HWMonitorStateObjectNames._intelcpu_0_load_0)]
public StateObjectNotifier CPU { get; set; }

Comme vous le savez, le StateObjectNotifier implémente l’interface INotifyPropertyChanged. Vous pouvez donc lier cette propriété dans votre vue XAML pour voir votre StateObject en temps réel sur votre interface.

Nous allons modifier le label “Hello World” pour afficher en temps réel votre consommation CPU. Pour cela changeons le contenu (Content) du label avec la propriété “Value” du StateObject publié par le package HWMonitor.

Cette propriété contient la valeur (ici de l’utilisation du CPU) avec un nombre décimal. Nous ajoutons également l’attribut “ContentStringFormat” pour n’afficher que 2 chiffres après la virgule.

Pour pourvoir utiliser des propriétés .NET comme binding dans votre vue XAML, vous devez spécifier le DataContext de votre fenêtre vers votre classe MainWindow soit via le code (this.DataContent = this) ou soit directement dans votre vue XAML en ajoutant cette attribut sur l’élément Window :

DataContext="{Binding RelativeSource={RelativeSource Self}}"

Résultat, vous pouvez suivre en temps réel le CPU ici de la machine “PO-SEB” :

Allons un peu plus loin en ajoutons dans notre code C#, un nouveau StateObjectLink :

[HWMonitorStateObjectLink(HWMonitorStateObjectNames._intelcpu_0_load_0)]
public StateObjectCollectionNotifier CPUs { get; set; }

Ce “lien” ne précise que le nom du StateObject (ici “/intelcpu/0/load/0”) et le package (HWMonitorStateObjectLink est la classe générée qui spécifie implicitement le package à “HWMonitor).

De ce fait, toutes les consommations CPU mesurées par les instances du package HWMonitor seront captées par ce “link” ! On utilisera donc un StateObjectCollectionNotifier car on aura autant de StateObjects qu’on a d’instance de ce package.

Dans la vue XAML, ajoutons un menu déroulant (combobox) pour afficher le nom des sentinelles (= le nom des machines) des StateObjects de votre collection “CPUs” :

Enfin, modifions une nouvelle fois notre label. Cette fois ci la valeur à afficher n’est pas celle du StateObject “CPU”, mais celle du StateObject sélectionné par la combobox :

On obtient donc la possibilité de suivre la consommation de chaque machine (= sentinelle) où le package HWMonitor est déployé :

Pour terminer on pourrait également ajouter un StateObjectLink qui contiendrait TOUS les StateObjects produits par les packages HWMonitor, peut importe le nom du StateObject et la sentinelle :

[HWMonitorStateObjectLink]
public StateObjectCollectionNotifier HWMonitor { get; set; }

Pour afficher toutes ces données, on peut utiliser un DataGrid lié à votre collection de StateObject “HWMonitor” :

On obtiendrait une vue avec deux colonnes, la propriété DynamicValue et Value des StateObjectNotifier :

Pour rendre cela plus visuelle, définissions explicitement des colonnes avec le nom de la sentinelle, le nom du StateObject, la propriété “Name” de la valeur du StateObject (le nom du compteur), la “Value” et l’unité de la mesure (Unit).

En XAML cela se traduit par le code suivant :

Le résultat :

Prenez garde car les StateObjects sont mis à jour dans le StateObjectsCollectionNotifier par des threads différents. Vous risquez donc d’avoir des exceptions du type “An ItemsControl is inconsistent with its items source”. Afin d’éviter ce genre d’erreur, utilisez la méthode “BindingOperations.EnableCollectionSynchronization”.

Pour cela, dans votre classe, ajoutez un objet de synchronisation :

private static object _syncLock = new object();

Puis dans le constructeur de votre fenêtre, après le InitializeComponent(), activez la synchronisation de la collection sur votre StateObjectCollectionNotifier (ici nommé ‘HWMonitor’) :

BindingOperations.EnableCollectionSynchronization(HWMonitor, _syncLock);

Si lancez votre package dans une Constellation avec plusieurs instances du packages HWMonitor sur vos différentes sentinelles, vous aurez une vision temps réel de l’ensemble de vos machines Windows avec seulement ces quelques lignes de XAML et Constellation :

Déployez votre package UI

Publier le package

Le sujet a été traité dans le guide de démarrage, il suffit de cliquer-droit sur votre projet et sélectionner dans le menu Constellation “Publish On Constellation” ou directement depuis la toolbar :

Vous pourrez alors choisir le type de publication (Local ou Upload sur le serveur Constellation) :

Déployer le package sur une sentinelle UI

Vous devez impérativement déployer un package “UI” sur une sentinelle UI. Si vous tentez d’ajouter un package UI sur une sentinelle service, le package démarrera mais aucune fenêtre ne pourra être visible (le service ne peut pas interagir avec le bureau Windows).

Les sentinelles UI ont le suffixe “_UI” dans leurs noms. Ici pour cette Constellation, il y a deux sentinelles connectées, l’une de type “Service” et l’autre “UI”, toutes deux sur la même machine (nommé “PO-SEB”).

Pour ajouter notre package à la sentinelle UI, vous pouvez éditer la configuration de vos Constellation directement depuis Visual Studio :

Ou bien depuis la Console Constellation :

Pour déployer la configuration, cliquez sur le bouton “Save & Deploy” depuis la Console, ou directement sur la page des “Packages” cliquez sur “Reload & Deploy”.

Votre package UI sera démarré et vous pourrez le contrôler depuis la Console comme pour les autres packages.

Démarrer son package “manuellement”

Si vous créez une application à destination d’une borne d’affichage, comme un miroir, le package est démarré automatiquement par la sentinelle (comportement par défaut) et est relancé si le package plante !

Cependant, si votre package est destiné à être utilisé par un utilisateur comme une application Windows classique vous voudriez certainement ne pas la lancer automatiquement au démarrage de la sentinelle. Au contraire vous voudriez que ce soit l’utilisateur qui décide de la lancer en lançant un raccourci Windows par exemple sans devoir se connecter sur la Console de votre Constellation.

Pour cela vous pouvez lancer la sentinelle en passant un ordre en paramètre :

Constellation.Sentinel.UI.exe

Les actions peuvent être :

Start
Stop
Restart
Reload

Par exemple, créons un raccourci sur le bureau vers :

Constellation.Sentinel.UI.exe Reload MonPackageWPF

Ainsi dès que vous double-cliquerez sur ce raccourci, la sentinelle téléchargera la dernière version du package sur le serveur et lancera votre package (Reload) :

Bien entendu, l’état du package sera automatiquement synchronisé dans la Constellation. Vous pourrez donc contrôler l’état du package depuis la Console par exemple.

Par défaut, une sentinelle démarre tous les packages qui lui sont assignés. Si c’est un package destiné à être lancé manuellement par l’utilisateur, vous voudriez peut être ne pas lancer automatiquement le package. Vous pouvez donc définir l’attribut “autoStart” à false au niveau de la configuration de votre package.

Aussi l’ordre d’arrêt d’un package doit provenir du hub de contrôle de Constellation, qui se chargera de communiquer l’ordre au package lui même (de s’arrêter) et à sa sentinelle (de tuer le package si il ne s’est pas arrêté dans le temps imparti).

Seulement, dans un package UI de ce type, c’est à dire “application Windows classique”, l’utilisateur fermera naturellement l’application en cliquant sur la croix rouge en haut à droite !

La sentinelle détectera la mort du processus du package alors qu’elle n’a pas eu l’ordre de Constellation d’arrêter le package ! Du point de vue de la sentinelle, c’est un arrêt brutal !

Elle appliquera donc les options de récupération qui par défaut redémarre un package 30 secondes après un arrêt brutal :

Les options par défaut sont définis dans la configuration de la Constellation :

Dans notre cas, nous allons redéfinir ces options de récupération au niveau du package lui même pour ne pas redémarrer un package suite à un arrêt forcé et ne pas démarrer automatiquement notre package au démarrage. La configuration du package sera :

The post Créer des packages UI en Winform ou WPF appeared first on Constellation.