Les fichiers de paramètres

La configuration de votre application (serveur de mail, démarrage du serveur web, conservation de l'historique, licence, redirections) vit dans des fichiers placés dans Resources/json et fusionnés dans le Storage au démarrage. APP_PARAMETERS en est le socle ; les autres fichiers le surchargent selon la machine.

Les fichiers

• Pas d'extension : les noms sont exacts (APP_PARAMETERS, pas APP_PARAMETERS.json).
• Chiffrés sur le disque : modifiez-les avec l'éditeur d'objets JSON, jamais avec un éditeur de texte.
• Le suffixe de DEV_PARAMETERS_<suffixe> n'est qu'une convention (le nom d'un développeur, par exemple) : rien ne choisit un fichier selon la machine ou l'utilisateur, tous ceux qui existent sont chargés.
• L'installation copie des modèles de APP_PARAMETERS, DEV_PARAMETERS, PREPROD_PARAMETERS et WEB_PARAMETERS dans votre projet, s'ils n'y sont pas déjà.

Ces fichiers sont propres à chaque machine : ne les versionnez pas et ne les livrez pas. Ils contiennent des secrets (le mot de passe du serveur de mail, la licence…), et transporter un fichier écraserait la configuration de l'autre côté. Le build les retire de l'application livrée (sauf WEB_PARAMETERS) : chaque serveur garde les siens.

L'ordre de chargement et la fusion

Au démarrage, l'application part du mode PROD, puis lit, dans cet ordre :

APP_PARAMETERS → WEB_PARAMETERS → PREPROD_PARAMETERS → DEV_PARAMETERS → les DEV_PARAMETERS_*

Un fichier lu plus tard l'emporte sur un fichier lu plus tôt, selon ces règles :

« Sur un seul niveau » veut dire : dans vo_Param, une valeur simple est remplacée par celle du fichier suivant, mais un objet imbriqué est remplacé en entier. Un DEV_PARAMETERS qui veut seulement changer le serveur de mail doit donc reprendre tout vo_Mail, pas seulement vt_Host : sinon le port, l'utilisateur et le mot de passe disparaissent.

Un paramètre se range donc dans un objet racine, presque toujours vo_Param :

{
  "vo_Param": {
    "vt_RedirectMail": "moi@exemple.fr",
    "vo_Mail": { "vt_Host": "smtp.exemple.fr", "vl_Port": 587, "vt_User": "…", "vt_Password": "…", "vt_Forwarder": "…" }
  }
}

Le mode de l'application

Storage.vo_Param.vt_applicationMode vaut PROD, PREPROD ou DEV (et COMPONENT quand le composant est ouvert seul). DEV l'emporte sur PREPROD. Les fichiers DEV_PARAMETERS_* ne changent pas le mode.

Une installation neuve démarre en mode DEV, puisque l'installation copie un modèle DEV_PARAMETERS. Supprimez-le, ainsi que PREPROD_PARAMETERS, sur un serveur de production.

Quelques outils (l'instantané d'échange du contenu, l'archivage de l'historique, le dialogue de confirmation du démarrage) se fient, eux, à la seule présence d'un fichier dont le nom commence par DEV_PARAMETERS. Avec un seul DEV_PARAMETERS_<suffixe>, ils considèrent la machine comme une machine de développement alors que le mode reste PROD.

Les principales clés

Toutes sous vo_Param :

Lire un paramètre

• Dans votre projet : Storage.vo_Param.<clé>. Votre projet a son propre Storage ; le bloc Use (Storage) que l'installation ajoute à Sur ouverture y recopie vo_Param au démarrage (voir Le lanceur, le démarrage et la barre d'outils). Les autres objets racine ne sont pas recopiés.
• Dans le composant : Storage.vo_Param.<clé> ou Storage.<objet racine>.<clé>.

Modifier un paramètre

Avec l'éditeur d'objets JSON, puis redémarrez : l'enregistrement du fichier ne recharge rien, et le rafraîchissement du Storage (BSPK_REFRESH_STORAGE) ne relit pas ces fichiers.

Une clé nouvelle, dont une nouvelle version de votre application a besoin, s'ajoute par une méthode de mise à jour : lire le fichier (BSPK_FILE_Get_JSON_Content), ajouter la clé seulement si elle est absente, réécrire le fichier (BSPK_FILE_SET_JSON_CONTENT). Jamais en livrant le fichier.

Au premier démarrage d'un serveur

Si votre projet n'a pas de Resources/json/APP_PARAMETERS, le démarrage ouvre un dialogue « Select APP_PARAMETERS files » (sont acceptés APP_PARAMETERS, PREPROD_PARAMETERS et DEV_PARAMETERS), copie les fichiers choisis, et quitte 4D si le dialogue est annulé ou si personne n'est là pour y répondre. Une application livrée n'embarquant aucun fichier de paramètres, c'est le passage obligé de toute nouvelle installation serveur.

Bon à savoir

• Une valeur simple posée à la racine du fichier n'arrive jamais dans le Storage, sans erreur ni trace.
• Une date enregistrée en texte ISO revient sous forme de date 4D : voir Le langage 4D.
• Une clé retirée d'un fichier reste dans le Storage jusqu'au redémarrage.

Voir aussi

• L'éditeur d'objets JSON
• La classe Mail
• Le lanceur, le démarrage et la barre d'outils