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<Program>(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 <appSettings> 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 :

<setting key="MyBoolSetting" value="true" />      
<setting key="MyStringSetting" value="This is a string" />
<setting key="MyIntSetting" value="123" />

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<int>("MyIntSetting");
bool myBoolSetting = PackageHost.GetSettingValue<bool>("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 :

<setting key="MyXmlDocument">
  <content>
    <note date="09-02-2016">
      <to>Tove</to>
      <from>Jani</from>
      <heading>Reminder</heading>
      <body>Don't forget me this weekend!</body>
    </note>
  </content>
</setting>

<setting key="MyJsonObject">
  <content>
    <![CDATA[
    {
      "Number": 123,
      "String" : "This is a test (local)",
      "Boolean": true
    }
    ]]>
  </content>
</setting>

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<T> : 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<TConfigurationSection> : 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<MyCustomObject>("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<string, object> { { "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<Program>(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<int>("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 :

<Setting name="Interval" type="Int32" defaultValue="5000" description="Interval en millisecondes" />

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).

<package name="MonPremierPackage" enable="true">
    <settings>
        <setting key="Interval" value="2000" />
  </settings>
</package>

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.

Comme nous l’avons vu dans le tutoriel précèdent, 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 .NET !

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<MonPackage>(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.

1. Tout désinstaller et ré-installer la nouvelle installation
2. Migrer l’existant

Pour la première solution, il suffit simplement de tout désinstaller depuis l’ajout et suppression de programmes Windows  sans oublier de supprimer le répertoire du serveur. Puis en suivant le guide de démarrage, réinstaller la nouvelle version 1.8 en partant de zéro.

Bien entendu cette solution n’est valable que si votre Constellation n’est pas ou peu utilisée. Autrement si souhaitez migrer l’existant vers la nouvelle version 1.8 suivez ce guide.

Plan de migration

Pour mettre à jour une Constellation 1.7 vers la 1.8, voici le plan des étapes à réaliser :

1. Mise à jour du serveur
2. Mise à jour de la Console
3. Mise à jour des pages Web (ou assimilés) exploitants l’API JavaScript
4. Mise à jour du SDK
5. Mise à jour des sentinelles
6. Mise à jour des packages

Mise à jour du serveur

La première étape consiste à mettre à jour le serveur de façon à migrer votre Constellation 1.7 en 1.8.

L’installeur tout-en-un “Platform” ou l’installeur propre au serveur réalise la migration automatiquement (en tenant compte de votre configuration actuelle).

Prenons l’exemple d’une installation avec le serveur Constellation 1.7.6 déployé, la Console (nommée “Control Center” dans la version 1.7) et une sentinelle 1.7 sur laquelle est déployé le package HWMonitor également en version 1.7 :

Pour mettre à jour le serveur, la console et la sentinelle en une seule fois, je vous recommande de lancer l’installeur tout-en-un “Platform”.

L’installeur vous informera alors que ces trois composants seront mis à jour vers la version 1.8 :

A la fin de l’installation, dans les services Windows vous pourrez constater que les services du serveur et de la sentinelle ont bien été mis à jour :

Vous pouvez également vous rendre sur l’URI de votre Constellation pour vérifier que le serveur Constellation 1.8 est bien démarré.

Notez que toute votre configuration est restée échangé (clé d’accès, sentinelle, configuration des  packages, etc…).

Mise à jour de la Console

Avec l’installeur “Platform” ci-dessus, la nouvelle Console (anciennement “Control Center”) est bien déployée.

Il vous suffit de réactualiser la page et vous retrouverez votre sentinelle (elle aussi migrée en 1.8 via l’installeur Plateform) et votre package HWMonitor (toujours fonctionnel dans votre nouvelle Constellation) :

Activer la page de login et l’accès à l’API de Management

Comme pour le serveur, l’installeur garde votre configuration actuelle lors de la mise à jour vers Constellation 1.8.

De ce fait, la configuration de la Console se trouve toujours dans le fichier “config.js” à la racine du répertoire d’installation de la Console.

Jusqu’à la version 1.7, ce fichier devait contenir une clé d’accès avec l’autorisation d’accès au hub de contrôle. Depuis la version 1.8, vous n’êtes plus obligé de définir en dur la clé d’accès dans ce fichier. Si la variable est vide, la console proposera alors une page de login.

L’idée est donc d’utiliser un couple login/password qu’on “hashera” pour l’utiliser en tant que clé d’accès (il est plus simple de mémoriser un login/password qu’une longue clé d’accès). Nous allons donc changer la clé d’accès (ou en créer une nouvelle) en utilisant ce procédé.

De plus dans Constellation 1.8, une nouvelle API est apparue pour l’administration du serveur : l’API de Management. Il vous faudra ajouter l’autorisation d’y accéder sur votre Access Key :

Etape 1 : créez une Access Key à partir d’un login/password

Rendez-vous sur un outil de création de hash SHA1 tel que http://www.sha1.fr/ et créez un hash SHA1 du login concaténé avec votre mot de page.

Par exemple, si mon login est “seb” et mon mot de passe “Password”, je crée le hash de “sebPassword” ce qui me retourne “567841343531a170817ac02941d644df12d7d3ae”.

Etape 2 : déclarez votre nouveau credential

Editez le fichier de configuration du serveur (“Constellation.Server.exe.config” dans le répertoire d’installation du serveur) et ajoutez dans la section <credentials>:

<credential name="MyAdminAccess" accessKey="567841343531a170817ac02941d644df12d7d3ae" enableControlHub="true" enableManagementAPI="true" enableDeveloperAccess="true"/>

Le nom du credential n’a peu d’importance (il ne sert que pour votre organisation), l’AccessKey est le hash SHA1 généré à partir de notre login & password, et n’oubliez pas d’autoriser l’accès au Control Hub (enableControlHub) et également à l’API de management (enableManagementAPI).

SI vous souhaitez également utiliser cette clé d’accès pour débugger vos packages depuis le SDK Visual Studio, activez l’accès développeur (enableDeveloperAccess).

Depuis la Console, cliquez sur le bouton “Reload Config” pour recharger la configuration avec votre nouveau credential :

Etape 3 : mettez à jour le fichier de configuration de la Console

Editez maintenant le fichier de configuration de la Console (fichier “config.js” dans le répertoire d’installation de la config).

Commencez par supprimer l’ajout de l’ancien menu en retirant les lignes :

$(document).one('pagebeforecreate', function() {
    $.get("menu.html", function(data) {
        $.mobile.pageContainer.prepend(data);
        $("#nav-panel").panel();
        $("#menu-list").listview();
    });
});

Puis effacer le contenu de la variable “constellationAccessKey” pour forcer l’affichage de la page de login.

Au final, le contenu de votre fichier “config.js” doit être (en reprenant soin de spécifier l’URI de votre serveur Constellation en fonction de votre installation) :

// Constellation Server URI
var constellationUri = "http://localhost:8088";
// Constellation AccessKey (w/ enableControlHub)
var constellationAccessKey = ""; // leave empty to enable the login page

Vous pouvez ensuite rafraichir votre page (Ctrl+F5 de préférence), la page de login s’affichera car aucune clé d’accès n’est définie dans le fichier “config.js”.

Pour vous connecter, utilisez votre login/password afin d’accéder à la console.

SI vous avez activé l’accès à l’API de Management (enableManagementAPI), vous aurez un nouveau menu “Server Management” ajoutant des fonctionnalités pour la gestion du serveur, comme l’édition du fichier de configuration de serveur directement depuis la Console :

Optionnel : auto-hébergement de la Console par le serveur Constellation

Depuis la version 1.8, le serveur Constellation est capable d’héberger des pages Web ce qui permet d’héberger la Console Constellation sans avoir besoin d’installer un serveur Web type IIS, Apache ou autre.

Pour cela, vous devez simplement éditer la configuration du serveur pour activer le “File Server” :

<fileServer enable="true" physicalPath="..\Console\" localhostOnly="true" path="/WebConsole"/>

Passez l’attribut “enable” à true, indiquez le chemin physique du répertoire d’installation de la Console (par exemple : c:\inetpub\wwwroot), si vous voulez limiter ou non la console en local et l’URL relatif de la console (par default /webconsole/).

Pour prendre en compte ces modifications vous devez redémarrer le serveur Constellation (dans la MMC des Services Windows).

Aussi dans le fichier “config.js” de la Console, la variable “constellationUri” doit être vide pour indiquer que l’URI du serveur et la même que la console.

Mise à jour des pages Web (ou assimilés) exploitants l’API JavaScript

Depuis la version 1.8, plusieurs modifications ont été apporté au hub de contrôle et la 1.8 se voit doter d’un nouveau hub : le hub de consommation (Consumer Hub).

Historiquement le hub de contrôle (Control Hub) permettait à la fois de contrôler la Constellation mais également d’interroger les StateObjects, envoyer et recevoir des messages, etc… car c’était le seul hub disponible pour le Web (Javascript).

Avec Constellation 1.8, le hub de contrôle est exclusivement dédié au contrôle de la Constellation (gestion des packages, récupération des statuts, des logs, reload de la configuration, etc…). Toutes les méthodes liées aux messages et aux StateObjects ont été déplacé dans un nouveau hub : le hub de consommation.

Une fois votre serveur migré en 1.8, toutes les pages Web (ou assimilés type applications Tizen ou Cordova qui utilisent l’API Javascript) ne fonctionneront plus tant que vous n’aurez pas migrés les API Javascript 1.8

Etape 1 : supprimez les anciennes librairies

Tout d’abord, commencez par désinstaller les packages Nuget “Constellation.CommonJS” (API Constellation JS) et “Constellation.CommonNG” (API Constellation AngularJS) car il s’agit des anciens packages pour Constellation 1.7.

Si vous n’avez pas utilisé Nuget pour installer ces librairies, supprimez manuellement les fichier “Constellation.js” et “ngConstellation.js”.

Etape 2 :  installez les nouvelles librairies

Depuis Nuget, installez le ou les nouveaux packages :

• “Constellation.Javascript” pour la libraire Constellation pour Javascript
• “Constellation.Angular” pour la librairie Constellation pour AngularJS (sur couche)

Dans vos pages HTML, changez les liens vers les nouveaux fichiers Javascript portant désormais le numéro de version de l’API.

Remplacez :

<script type="text/javascript" src="/constellation/Scripts/Constellation.js"></script>
<script type="text/javascript" src="/constellation/Scripts/ngConstellation.js"></script>

par :

<script type="text/javascript" src="/constellation/Scripts/Constellation-1.8.0.js"></script>
<script type="text/javascript" src="/constellation/Scripts/ngConstellation-1.8.0.js"></script>

Etape 3 : modification dans l’API

Pour l’API Javascript (Constellaiton.Javascript), la méthode “createConstellationClient” est remplacée par “createConstellationConsumer” pour l’accès au hub de consommation ou “createConstellationController” pour l’accès au hub de contrôle.

Pour l’API AngularJS (Constellation.Angular), le module “constellation” à injecter dans votre contrôleur est remplacé par “constellationConsumer” et “constellationController” pour les deux hubs. La méthode “intializeClient” reste inchangée et est disponible sur les deux modules.

Mise à jour du SDK

Lancez tout simplement l’installeur tout en un “Platform” ou l’installeur du SDK.

Il procèdera à l’installation du VSIX pour Visual Studio 2012, 2013 et 2015.

Mise à jour des sentinelles

Les sentinelles 1.7 peuvent fonctionner sans aucun soucis dans une Constellation 1.8 (à l’inverse, une sentinelle 1.8 ne peut pas se connecter à une Constellation 1.7).

Cependant, afin de bénéficier des nouveautés de la 1.8, il est conseillé de mettre à jour ses sentinelles.

Pour cela, vous devez soit lancer l’installeur “Plateform” si vous être sur la même machine que votre serveur Constellation, ou lancer l’installeur dédié à la sentinelle Service ou UI :

Mise à jour des packages

Comme nous l’avons vu avec les API Javascript, les requêtes (Request) et abonnements (Subscribe) sur les StateObjects et l’envoi et la réception de messages ne sont plus disponibles sur le hub de contrôle.

Ainsi les packages .NET ou Python qui utilisaient ces fonctionnalités comme les [StateObjectLink] ne pourront plus fonctionner une fois votre serveur Constellation migré en 1.8. Vous devez donc impérativement mettre à jour la librairie Constellation 1.8 pour ces packages.

Autrement, pour tous les packages Constellation 1.7.x qui n’exploitent pas les StateObjects (hormis le Push) et n’utilisent pas les fonctionnalités du hub de contrôle, pourront fonctionner sans problème sur une Constellation 1.8.

Au démarrage vous aurez simplement un warning (et seulement si la sentinelle est en version 1.8.x) :

Pensez toutefois à mettre à jour la libraire cliente Constellation pour bénéficier des nouveautés de la 1.8.

Mise à jour du package Constellation 1.8

Comme pour les API Javascript, le package NuGet de l’API .NET a changé d’identifiant. Vous devez donc commencer par désinstaller le package Constellation 1.7 nommé “Constellation.Common” :

Puis, toujours depuis NuGet, installez le package “Constellation” 1.8 :

Les breaking changes

Une fois vos projets migrés sur la nouvelle librairie 1.8, il y a plusieurs “breaking changes” que vous devrez corriger pour pouvoir compiler votre package. Retrouvez ci-dessous la liste des changements bloquants (et non la liste des nouveautés de l’API 1.8).

Le Namespace

Premièrement l’espace de nom “Constellation.Host” devient “Constellation.Package”. Vous devez donc changer les différents “using” de votre code.

using Constellation.Package;

Le PackageManifest

L’attribut « RestoreStateObjects » est renommé en « RequestLastStateObjectsOnStart » dans le manifest (PackageInfo.xml) de votre package. Il permet d’indiquer au serveur Constellation de vous envoyer les derniers StateObjects du package quand il démarre (avant la purge).

De même, l’évènement « RestoreStateObjects » est lui renommé en « LastStateObjectsReceived » sur la classe statique “PackageHost” :

PackageHost.LastStateObjectsReceived += (s, e) =>
{
     PackageHost.WriteInfo("Recu {0} StateObject(s)", e.StateObjects.Count);
};

Les Settings

La version 1.7 de Constellation a introduit les “SettingContents” permettant de mettre du XML dans la déclaration d’un setting. Il fallait alors utiliser la méthode « GetSettingContent<TConfigurationSection> » où TConfigurationSection devait être une ConfigurationSection.

En 1.8, cette méthode a été renommé en « GetSettingAsConfigurationSection<TConfigurationSection>« .

De plus de nouvelles méthodes sont apparues :

MaSection section = PackageHost.GetSettingAsConfigurationSection<MaSection>("MaSection");
dynamic configJson = PackageHost.GetSettingAsJsonObject("MonObjectJson");
MonObject objetJson = PackageHost.GetSettingAsJsonObject<MonObject>("MonObjectJson");
XmlDocument xml = PackageHost.GetSettingAsXmlDocument("MonXml");

Lorsque le package est démarré en mode “debug”, depuis Visual Studio, les SettingValues sont lues depuis les <appSettings> de votre App.config. Avec la 1.8, les <appSettings> sont abandonnés. Vous devez définir une section “constellationSettings” qui prend la même structure que les settings sur le serveur avec le support des <content>.

Pour plus d’information, consultez la page dédiée à la configuration des packages.

Les StateObjects

• Désormais la propriété “Metadatas” d’un StateObject est dictionnaire de String (clé) / Object (valeur) (et non plus String/String).
• La classe  StateObject est maintenant dans le namespace racine “Constellation”
• Les classes StateObjectNotifier et StateObjectCollectionNotifier ainsi que l’attribut StateObjectLink et les EventsArgs associés appartiennent au namespace “Constellation.Package”
• Les notions  des StateObjectsLink & Notifier (méthodes et events) sont déplacés dans le PackageHost et non plus dans le ControlManager.

Il n’y a donc plus besoin de définir l’attribut “EnableControlHub” à true pour ajouter des StateObjectsLinks dans vos packages.

Les messages

La méthode PackageHost.AttachMessageCallbacks est renommée en PackageHost.RegisterMessageCallback. A noter qu’elle est (toujours) implicitement appelée au démarrage du package sur votre package “PackageBase”.

Les méthodes PackageHost.CreateScope & PackageHost.CreateSaga ont été supprimées. Pour créer un scope vous devez directement utiliser la classe MessageScope.

Par exemple :

MessageScope scope = MessageScope.Create("MonPackageCible");
MessageScope scope2 = MessageScope.Create(MessageScope.ScopeType.Group, "GroupA", "GroupB");

Breaking change : ScopeType.Groups est devenu ScopeType.Group (au singulier)

Pour récupérer le proxy dynamic, vous devez utiliser la méthode d’extension “GetProxy” et non plus la propriété “Proxy” :

dynamic proxy = scope.GetProxy();

Par exemple, pour envoyer le message “Demo” au package “DemoPackage” :

MessageScope.Create("DemoPackage").GetProxy().Demo("Un argument ici !");

Pour envoyer ce message dans une saga, vous devez attacher à un callback de retour avec la méthode d’extension “OnSagaResponse” :

MessageScope.Create("DemoPackage").OnSagaResponse(reponse =>
{
     PackageHost.WriteInfo("Recu reponse de {0}", MessageContext.Current.Sender.FriendlyName);
}).GetProxy().Demo("Un argument ici !");

Par défaut, la variable de retour est un dynamic, mais vous pouvez aussi spécifier le type de retour :

MessageScope.Create("DemoPackage").OnSagaResponse<MonObject>(reponse =>
{
     // Reponse est de type MonObject
     PackageHost.WriteInfo("Recu reponse de {0}", MessageContext.Current.Sender.FriendlyName);
}).GetProxy().Demo("Un argument ici !");

Pour finir, il ne s’agit pas d’un breaking change mais d’une nouveauté : vous pouvez également envoyer un message dans une saga de façon “awaitable” :

Task<dynamic> reponse = MessageScope.Create("DemoPackage").GetProxy().Demo<MonObject>("Un argument ici !");

Retrouvez plus d’information sur l’envoi de message et les sagas sur cette page.

The post Migrer Constellation 1.7 vers Constellation 1.8 appeared first on Constellation.