Ce fichier se nomme “Constellation.Server.exe.config” et se trouve dans le répertoire d’installation du serveur (par défaut dans “Program Files\Constellation Plateform\Server« ).

Vous pouvez le modifier de différente manière :

• En éditant ce fichier directement sur le serveur (avec un éditeur de texte type Notepad)
• Via la Console Constellation (sur la page Configuration Editor)
• Via Visual Studio
• Via l’API de Management Constellation

Le fichier contient une balise globale “configuration” dans laquelle vous trouverez 4 sections :

• configSections : réservé au moteur .NET
• constellation : la section de configuration Constellation (anciennement nommée ‘constellationSection’)
• startup : réservé au moteur .NET
• runtime : réservé au moteur .NET

Vous ne devez en aucun cas modifier les sections réservées au moteur .NET sans savoir exactement ce que vous faites.

La section de “constellation” se décompose de la façon suivante :

• listenUris : définit la configuration des URI d’écoute du serveur Constellation
• fileServer : définit la configuration du serveur Web statique utilisé pour l’hébergement de la Console Constellation
• recoveryOptions : définit les options de récupération des packages
• sentinels : définit la configuration des sentinelles (et des packages) de votre Constellation
• settingsGroups : définit la configuration des groupes de “settings”
• credentials : définit la configuration des credentials pour l’accès à votre Constellation

A chaque modification vous devez recharger la configuration soit via le hub de contrôle ou la Console Constellation (bouton “Reload Configuration”) ou soit en redémarrant le service Constellation Server.

Section “listenUris”

Cette section permet de définir les URI sur lesquels le serveur Constellation doit écouter.

<listenUris>
  <uri listenUri="http://+:8088/" />
</listenUris>

Ici le serveur répondra sur le port HTTP 8088 quelque soit le host (nom DNS ou adresse IP) car nous utilisons le wildcard “+” (pour plus d’information, lisez ceci).

Vous pouvez configurer autant de “listenUri” que vous souhaitez. Par exemple :

<listenUris>
  <uri listenUri="http://+:8088/" />
  <uri listenUri="http://constellation.mydomain.net:8888/" />
  <uri listenUri="http://+:8080/constellation/" />
  <uri listenUri="https://+:8089/" />
</listenUris>

Ici, le serveur Constellation répondra :

• Aux requêtes sur le port HTTP 8088
• Aux requêtes sur le port HTTP 8888 où le host est “constellation.mydomain.net” (en clair une requête http://<ip>:8888  ne fonctionnera pas)
• Aux requêtes sur le port HTTP 8080 quelque soit le host mais dont le path doit forcement démarrer par “/constellation/”
• Aux requêtes sur le port HTTPS 8089 en utilisant un cryptage SSL (plus d’information)

Pour prendre en compte les modifications de cette section vous devez redémarrer le service Constellation.

Section “fileServer”

Cette section permet d’activer et configurer le “fileServer” de Constellation pour héberger des fichiers statiques (pages HTML, fichiers CSS, JS, images, etc..).

Cela sert principalement pour “auto-héberger”  la Console Constellation par le serveur Constellation lui-même.

En effet, la Console Constellation n’est ni plus ni moins qu’une application Web client-side, c’est à dire une série de pages HTML avec scripts JS et fichiers CSS/Image. Libre à vous de l’héberger sur vos serveurs Web mais afin de limiter les prérequis, le serveur Constellation peut lui-même héberger la console grâce au “fileServer” intégré.

La section “fileServer” ne contient que quatre attributs :

<fileServer enable="true" path="/WebConsole" localhostOnly="true" physicalPath="D:\App\Constellation\Console" />

• “enable” : indique si le serveur de fichier statique sur le serveur Constellation doit être activé (true ou false).
• “path” : le répertoire d’écoute (préfixé par la listenUri).
• “localhostOnly” : indique si le fileServer répond seulement aux requêtes “locales” ou à toutes les requêtes (true ou false).
• “physicalPath” : le répertoire physique

Dans l’exemple ci-dessus, le serveur de fichier est activé mais ne répondra qu’aux requêtes locales. Le serveur délivra les fichiers dans “D:\App\Constellation\Console” sur l’URL “<listen_URI_du_serveur_Constellation>/WebConsole” par exemple http://localhost:8088/WebConsole ou http://127.0.0.1:8088/WebConsole en partant du principe qu’il existe une listenUri “http://+:8088”.

Comme pour la section précédente (listenUris), il faut obligatoirement redémarrer le service Constellation Server pour prendre en compte ces modifications.

Section “recoveryOptions”

Les options de récupération (recoveryOptions) permettent de définir le comportement de la sentinelle en cas d’arrêt brutale de l’exécution d’un package (crash du package).

Chaque package peut avoir ses propres options de récupération mais cette section permet de définir les options “globales”, c’est à dire appliqué par défaut pour chaque package de la Constellation.

Les options de récupérations se résume en quatre propriétés :

• “restartAfterFailure” (true par défaut) : définit si la sentinelle doit redémarrer un package en cas de crash de ce dernier
• “numberOfRetry” (3 par défaut) : définit le nombre maximal de tentative de redémarrage d’un package
• “restCounterAfterMinutes” (15 par défaut) : définit la période (en minute) au delà de laquelle le compteur d’erreur est réinitialisé
• “restartPackageAfterSeconds” (30 par défaut) : définit le délai d’attente avant de redémarrer un package suite à un crash

Dans la configuration par défaut, si un package “crash” il est automatiquement redémarré 30 secondes après son crash dans la limite de 3 tentatives sachant qu’au bout de 15 minutes, le compteur de tentative est réinitialisé à 0.

Section “sentinels”

Dans cette section vous allez déclarer vos sentinelles (virtuelles ou non) dans lesquelles vous déclarerez les packages (virtuels ou non) qui eux même déclarons leurs settings et leurs groupes.

En clair, c’est cette section qui décrit votre “Constellation”.

Prenez l’exemple de la Constellation suivante :

<sentinels>
  <sentinel name="SENTINEL-NAME-DEMO" credential="Standard">
    <packages>    
      <package name="HWMonitor" enable="true"></package>          
      <package name="DemoPackage" credential="ControlHubAccess" enable="true">
        <settings>
        <import>
          <settingGroup groupName="GroupSettingsDemo" />
        </import>
        <setting key="IntSetting" value="42" />
        <setting key="StringSetting" value="sample config value 2" />
        <setting key="SettingXml">
          <content>
            <demo type="test">
              <list count="42">
              <a>123</a>
              <b>test</b>
              </list>
            </demo>
          </content>
        </setting>
        <setting key="SettingJson">
          <content>
          <![CDATA[
          {
            ListenPorts: [ 80, 443 ],
            EnableCaching : true,
            ServerProgramName: "Hypothetical WebServer 1.0",
            Websites: [
              {
                Path: "/srv/www/example/",
                Domain: "example.com",
                Contact: "admin@example.com"    
              },
              {
                Path: "/srv/www/somedomain/",
                Domain: "somedomain.com",
                Contact: "admin@somedomain.com"
              }
            ]
          }
          ]]>
          </content>
        </setting>
        </settings>
      </package>
    </packages>
  </sentinel>
  <sentinel name="ANOTHER-SENTINEL" credential="Standard">
    <!-- ..... -->
  </sentinel>
</sentinels>

Voici ce qu’elle décrit :

• Nous avons deux sentinelles “SENTINEL-NAME-DEMO” et “ANOTHER-SENTINEL »
• Les deux sentinelles utilisent le même credential “Standard” (déclaré dans la section credentials).
• Sur la première sentinelle est déployée deux packages :
  • “HWMonitor” : le package utilise le même credential que sa sentinelle (car non défini explicitement donc hérite du credential de sa sentinelle)
  • “DemoPackage” : ce package utilise le credential nommé “ControlHubAccess” et déclare les settings suivants :
    • IntSetting et StringSetting associés à des valeurs (numérique et string)
    • SettingXml et SettingJson associés à des contenus (XML et JSON)
    • Importe le groupes de settings nommé “GroupSettingsDemo” défini dans la section “settingsGroups”

Les sentinelles

Pour entrer dans le détail, vous allez déclarer dans la section “sentinels”, les sentinelles de votre Constellation que ce soit des sentinelles réelles ou virtuelles.

Pour cela, vous utiliser la balise “<sentinel>” qui comporte les attributs suivants :

• “name” : le nom de la sentinelle (obligatoire et unique)
• “credential” : le nom du credential (déclaré dans la section credentials) à utiliser pour l’authentification (obligatoire)

La section “<sentinel>” contient une collection de “<package>” rangée dans la balise “<packages>”. Chaque package peut-être réel ou virtuel.

Les packages

L’élément “<package>” contient les attributs suivants :

• “name”: le nom de l’instance du package (obligatoire et unique)
• “filename” (facultatif) : le nom du fichier du package à utiliser dans le repository (plus d’info)
• “enable” (facultatif, par defaut true) : indique si le package est activé ou désactivé
• “credential” (facultatif, utilise par défaut du credential de sa sentinelle) : spécifie le credential que le package va utiliser pour s’authentifier sur le serveur Constellation
• “autostart” (facultatif, par defaut true) : indique si le package doit automatiquement démarrer sur sa sentinelle ou juste être déployé (et donc démarré manuellement)

Un package peut contenir ensuite trois sous sections :

• “recoveryOptions” : définit les options de récupération du package (par défaut, la sentinelle utilise les options globales)
• “settings” : définit les paramètres/variables de configuration d’un package
• “groups” : définit les groupes dans lesquels le package sera abonné

Les options de récupérations

La balise est la même que la section globale.

Par exemple si on ne souhaite pas que le package redémarre en cas de crash, on peut écrire :

<package name="MonPackage" enable="true">
  <recoveryOptions restartAfterFailure="false" />
</package>

Les paramètres de configuration

Chaque package peut définir des paramètres de configuration 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” : il s’agit d’un couple clé/value
• Les “Setting Content”  : il s’agit d’un setting dont la valeur peut être un XML ou JSON

Dans l’exemple plus haut, le package “DemoPackage” contient à la fois des settings de type “value” et de type “content”.

Vous pouvez également regrouper des settings dans les groupes afin de les partager entre plusieurs package grâce aux settingsGroups. Toujours dans l’exemple précédent, le package “DemoPackage” inclut le groupe “GroupSettingsDemo”, un groupe de settings décrit dans la section ”settingsGroups”.

Pour plus d’information sur les settings, consultez l’article sur l’exploitation des settings avec l’API .NET.

Les groupes

Comme vous le savez, un message peut être envoyé à un groupe dans lequel des packages réels ou virtuels peuvent s’abonner.

Il y a deux manières d’abonner un package à un groupe :

• Soit par le package lui même en invoquant la méthode “SubscribeToMessage” via les différentes API Constellation misent à disposition
• Soit dans la configuration du package au niveau du serveur Constellation

Cela vous permet d’avoir la main sur l’appartenance des packages aux groupes que vous pouvez administrer sans devoir modifier vos packages (virtuels ou non).

La section “groups” sur un package permet de définir ces liens. Par exemple :

<package name="MonPackage" enable="true">
  <groups>
    <group name="MonGroupeA" />
    <group name="MonGroupeB" />
  </groups>
</package>

Ici le package “MonPackage” est abonné aux groupes “MonGroupeA” et “MonGroupeB”. En cas de modification des affectations aux groupes, il faudra redémarrer le package soit via vos applications en utilisant les API du hub de contrôle soit depuis la Console Constellation.

Section “settingsGroups”

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

<settingsGroups>
  <group name="HWMonitorSettings">
    <settings>
      <setting key="Interval" value="500" />
    </settings>
  </group>
</settingsGroups>

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

<package name="HWMonitor">
  <settings>
    <import>
      <settingGroup groupName="HWMonitorSettings" />
    </import>
  </settings>
</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 SettingValue ou des SettingContent :

<settingsGroups>
  <group name="test">
    <settings>
      <setting key="Demo1" value="Seb" />
      <setting key="Demo2" value="123" />
    </settings>
  </group>
  <group name="test2">
    <settings>
      <import>
        <settingGroup groupName="common" />
      </import>
      <setting key="Demo1" value="Sebastien" />
      <setting key="Demo2" value="2015" />
    </settings>
  </group>
  <group name="common">
    <settings>
      <setting key="MyStringSetting" value="This is a string" />
      <setting key="MyBoolSetting" value="true" />
      <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>
    </settings>
  </group>
</settingsGroups>

Pour bien comprendre, imaginez le package suivant :

<package name="DemoPackage">
  <settings>
    <import>
      <settingGroup groupName="test" />
      <settingGroup groupName="test2" />
    </import>
    <setting key="numberTest" value="42" />
    <setting key="Demo1" value="It’me" />
  </settings>
</package>

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

• numberTest = 42 (définit dans les settings du package)
• Demo1 = “It’s me” (définit dans les settings du package, cette valeur écrase celle des groupes importés)
• Demo2 = 2015 (définit 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éfinies par le groupe “common” (groupe importé dans le groupe “test2” lui même importé sur le package “DemoPackage”).

Section “credentials”

Comme évoqué dans l’article lié à la sécurité, tous les appels (http) au serveur Constellation doivent être authentifiés en utilisant une clé d’accès que l’on nomme “AccessKey”.

Ces clé d’accès sont liés à des credentials.

Dans la section “credentials” nous allons donc définir les différents credentials ainsi que les différentes autorisations et droits sur ces credentials.

Chaque credential comporte obligatoirement deux propriétés :

• Le nom (unique) du credential
• L’AccessKey

Ainsi que les propriétés suivantes :

• “enable” (true par défaut) : indique si le credential est activé ou désactivé
• “enableControlHub” (false par défaut) : indique si le credential peut se connecter sur le hub de contrôle (pour l’administration de la Constellation)
• “enableManagementAPI” (false par défaut) : indique si le credential peut se connecter à l’API de Management (pour l’édition de la configuration)
• “enableDeveloperAccess” (false par défaut) : indique si le credential peut utiliser la sentinelle virtuelle “Developer” pour debugger des packages (utilisé par le SDK Visual Studio)

Par exemple :

<credentials>
  <credential name="Standard" accessKey="fb1af70a46057dbf4f2ff3f43b6ec0c544b22749" />
  <credential name="Administrator" accessKey="b363d6ccb86ef1418a72f9fea4b96975d8a1f2c7" enableControlHub="true" enableDeveloperAccess="true" enableManagementAPI="true" />
</credentials>

Vous pouvez ensuite définir des autorisations particulières sur un credential pour l’envoi de message, l’abonnement aux groupes de message ou encore l’interrogation de StateObject.

Pour cela il existe trois sous-sections :

• “stateObjects” : autorisations spécifiques pour l’interrogation (Request ou Subscribe) des StateObjects
• “messages” : autorisations spécifiques pour l’envoi de messages
• “groups” : autorisations spécifiques pour l’abonnement aux groupes

Les autorisations sur l’interrogation des StateObjects

Par défaut un credential actif (enable=true) peut interroger (Request ou Subscribe) tous les StateObjects de votre Constellation sans restriction.

Pour modifier ce comportement vous pouvez utiliser les autorisation sur les StateObjects.

Par exemple :

<credential name="Standard" accessKey="fb1af70a46057dbf4f2ff3f43b6ec0c544b22749">
  <authorizations>
    <stateObjects defaultAuthorization="Deny">
      <authorization id="Paradox" authorization="Allow" packageName="Paradox" />
      <authorization id="MonPC" authorization="Allow" sentinelName="PC-SEB" />
      <authorization id="LesCPU" authorization="Allow" packageName="HWMonitor" name="/intelcpu/load/0" />
      <authorization id="ServerRAM" authorization="Allow" sentinelName="SERVER" packageName="HWMonitor" name="/ram/load" />
    </stateObjects>
  </authorizations>
</credential>

Ici le credential “Standard” ne pourra pas interroger les StateObjects de la Constellation (defaultAuthorization = Deny) sauf pour les exceptions suivantes :

• Les StateObjects produits par le(s) instance(s) du package “Paradox”
• Les StateObjects produits par les packages (quel qu’il soit) de la sentinelle “PC-SEB”
• Les StateObjects nommés “/intelcpu/load/0” et produits par le package “HWMonitor” peu importe la sentinelle
• Le StateObject nommé “/ram/load” produit par le package “HWMonitor” sur la sentinelle “SERVER”

Vous devez donc définir l’autorisation par défaut (defaultAuthorization) et optionnellement ajouter une ou plusieurs exceptions avec l’élément <authorization> dont les attributs sont les suivants :

• “id” (obligatoire) : identifiant unique de l’autorisation
• “authorization” (facultatif – Allow par défaut) : type de l’exception (Allow ou Deny)
• “sentinelName” (facultatif – * par défaut) : sentinelle producteur du StateObject
• “packageName” (facultatif – * par défaut) : package producteur du StateObject
• “name” (facultatif – * par défaut) :  nom du StateObject

Les autorisations sur l’envoi de messages

Par défaut un credential actif (enable=true) peut envoyer un message à n’importe quel scope dans votre Constellation sans restriction.

Par exemple :

<credential name="Standard" accessKey="fb1af70a46057dbf4f2ff3f43b6ec0c544b22749">
  <authorizations>
    <messages defaultAuthorization="Deny">
      <authorization id="GroupA" authorization="Allow" scope="Group" args="A" />
      <authorization id="DemoSeb" authorization="Allow" scope="Package" args="DemoPackage" />
      <authorization id="TemperatureNest" authorization="Allow" scope="Package" args="Nest" messageKey="SetTargetTemperature"  />
    </messages>
  </authorizations>
</credential>

Ici le credential “Standard” ne pourra pas envoyer de message dans la Constellation (defaultAuthorization = Deny) sauf pour les exceptions suivantes :

• Messages envoyés au groupe “A”
• Messages envoyés au package “DemoPackage”
• Message “SetTargetTemperature” envoyé au package “Nest”

Vous devez donc définir l’autorisation par défaut (defaultAuthorization) et optionnellement ajouter une ou plusieurs exceptions avec l’élément <authorization> dont les attributs sont les suivants :

• “id” (obligatoire) : identifiant unique de l’autorisation
• “scope” (obligatoire) : type de scope pour le message (All, Group, Package ou Sentinel)
• “authorization” (facultatif – Allow par défaut) : type de l’exception (Allow ou Deny)
• “args” (facultatif) : les arguments du scope
• “messageKey” (facultatif) :  la clé du message

Les autorisation sur l’abonnement aux groupes

Par défaut un credential actif (enable=true) peut s’abonner à n’importe quel groupe sans restriction.

Par exemple :

<credential name="Standard" accessKey="fb1af70a46057dbf4f2ff3f43b6ec0c544b22749">
  <authorizations>
    <groups defaultAuthorization="Deny">
      <authorization groupName="A" />
    </groups>
  </authorizations>
</credential>

Ici le credential “Standard” ne pourra pas s’abonner à des groupes (defaultAuthorization = Deny) à l’exception du groupe “A”. Les attributs sont les suivants :

• “groupName” (obligatoire) : le nom du groupe
• “authorization” (facultatif – Allow par défaut) : type de l’exception (Allow ou Deny)

The post Le fichier de configuration appeared first on 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 <appSettings> 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 :

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

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

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

TryGetSettings

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

• TryGetSettingAsConfigurationSection<TConfigurationSection>
• TryGetSettingAsJsonObject
• TryGetSettingAsJsonObject<T>
• TryGetSettingAsXmlDocument
• TryGetSettingValue<T>

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<int>("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 <defaultContent> 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 :

<constellationSettings xmlns="http://schemas.myconstellation.io/Constellation/1.8/ConstellationSettings">
  <settings>
    <setting key="MyStringSetting" value="This is a string" />
    <setting key="MyBoolSetting" value="true" />
    <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>
  </settings>
</constellationSettings>

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 :

<package name="MonPackage" enable="true">
  <settings>
    <setting key="MyStringSetting" value="Valeur du serveur" />
  </settings>
</package>

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

<constellationSettings xmlns="http://schemas.myconstellation.io/Constellation/1.8/ConstellationSettings">
  <settings>
    <setting key="MyStringSetting" value="Valeur locale" />
    <setting key="MyIntSetting" value="42" />
  </settings>
</constellationSettings>

Avec dans son manifeste, la déclaration suivante :

<Settings>
   <Setting name="MyStringSetting" type="String" description="This is a String setting" />
   <Setting name="MyIntSetting" type="Int32" isRequired="false" ignoreLocalValue="true"  defaultValue="1234" />
</Settings>

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

<settingsGroups>
  <group name="HWMonitorSettings">
    <settings>
      <setting key="Interval" value="500" />
    </settings>
  </group>
</settingsGroups>

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

<package name="HWMonitor">
  <settings>
    <import>
      <settingGroup groupName="HWMonitorSettings" />
    </import>
  </settings>
</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 :

<settingsGroups>
  <group name="test">
    <settings>
      <setting key="Demo1" value="Seb" />
      <setting key="Demo2" value="123" />
    </settings>
  </group>
  <group name="test2">
    <settings>
      <import>
        <settingGroup groupName="common" />
      </import>
      <setting key="Demo1" value="Sebastien" />
      <setting key="Demo2" value="2015" />
    </settings>
  </group>
  <group name="common">
    <settings>
      <setting key="MyStringSetting" value="This is a string" />
      <setting key="MyBoolSetting" value="true" />
      <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>
    </settings>
  </group>
</settingsGroups>

Pour bien comprendre, imaginez le package suivant :

<package name="DemoPackage">
  <settings>
    <import>
      <settingGroup groupName="test" />
      <settingGroup groupName="test2" />
    </import>
    <setting key="numberTest" value="42" />
    <setting key="Demo1" value="It’me" />
  </settings>
</package>

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.