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

Création d'un package Constellation

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

Debugging Visual Studio

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

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

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

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 :

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

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 :

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 :

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 :

Autre exemple avec le setting JSON :

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 :

Pouvez également publié des objets anonymes :

Ou encore avec des types plus complexes :

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

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

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 :

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.

Debug dans Constellation

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

Debug dans Constellation

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

Debug dans 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 :

Enregistrement de la Constellation dans VS

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

Hello World Constellation

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

Hello World Constellation

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

StateObject Explorer

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

Visualisation des StateObjects

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

image

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

Publier un package Constellation

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

Publier un package Constellation

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 :

Publier un package Constellation

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

Package Repository

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

image

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

Edition de la configuration depuis VS

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

Intellisense

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 :

Upload de la configuration

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

Edition de la configuration

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 :

Console log temps réel

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

Contrôle des packages

Next steps

Créez votre premier package Constellation en C#
Editer la page sur GitHub
Étiqueté avec :                

Laisser un commentaire