Migrer Constellation 1.7 vers Constellation 1.8

Sommaire

Si vous avez une Constellation 1.7 déployée vous avez deux manière de migrer vers la 1.8 :

Tout désinstaller et ré-installer la nouvelle installation
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 :

Mise à jour du serveur
Mise à jour de la Console
Mise à jour des pages Web (ou assimilés) exploitants l’API JavaScript
Mise à jour du SDK
Mise à jour des sentinelles
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"/>

1	<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();
    });
});

$(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

// 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"/>

1	<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>

1 2	<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>

1 2	<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;

1	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);
};

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");

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");

1 2	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();

1	dynamic proxy = scope.GetProxy();

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

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

1	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 !");

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 !");

MessageScope.Create("DemoPackage").OnSagaResponse<MonObject>(reponse =>

{

// Reponse est de type MonObject