MQL5 · Expert Advisors
Structure d’un Expert Advisor MQL5 : directives, paramètres, OnInit, OnTick, OnDeinit
Directives, paramètres input, variables globales et fonctions événementielles : comment organiser le fichier d’un Expert Advisor MQL5, avec un squelette complet qui compile et les pièges à éviter.
Un Expert Advisor MQL5 est un fichier .mq5 organisé en zones bien distinctes : les directives (#property, #include), les paramètres d’entrée (input), les variables globales qui conservent l’état entre deux appels, puis les fonctions événementielles que le terminal appelle : OnInit au démarrage, OnTick à chaque nouveau prix, OnDeinit à l’arrêt. Respecter cette structure rend le code lisible, testable et facile à faire évoluer. Cette page décrit le rôle de chaque zone, propose un squelette complet et commenté, et liste les erreurs de structure les plus fréquentes.
Elle fait partie de la rubrique Construire un Expert Advisor en MQL5. Pour le détail de chaque fonction événementielle (signatures, ordre d’appel, cas des indicateurs et des scripts), reportez-vous à la page Les fonctions événementielles.
Les cinq zones d’un fichier d’EA
1. Les directives du préprocesseur
En tête de fichier, les directives #property renseignent les métadonnées affichées dans le terminal (version, description, copyright). Les directives #include importent du code externe, le plus souvent des classes de la bibliothèque standard comme CTrade (fichier Trade\Trade.mqh). Placez ici aussi vos #define de constantes. Ces lignes sont traitées avant la compilation proprement dite ; elles ne s’exécutent jamais pendant la vie de l’EA.
2. Les paramètres d’entrée
Les variables déclarées avec input apparaissent dans la fenêtre de propriétés de l’EA et dans le Strategy Tester, où elles peuvent être optimisées. Une variable input est en lecture seule dans le code : si vous devez la corriger (par exemple borner une valeur), copiez-la dans une variable globale lors de l’initialisation. Le mot-clé sinput déclare un paramètre statique, visible dans les propriétés mais exclu de l’optimisation : il convient au magic number ou à un commentaire d’ordre. Les nuances sont détaillées dans la page Paramètres input et sinput.
3. Les variables globales
Les variables déclarées en dehors de toute fonction conservent leur valeur entre deux appels d’OnTick. On y range les handles d’indicateurs, l’objet CTrade, la date de la dernière bougie traitée, des compteurs. Attention : ces variables sont réinitialisées quand l’EA est rechargé (changement d’unité de temps, modification des paramètres, redémarrage du terminal). Un état qui doit survivre à un redémarrage doit être sauvegardé ailleurs, comme expliqué dans la page Sauvegarder l’état dans des fichiers.
4. Les fonctions événementielles
Le terminal appelle ces fonctions lorsqu’un événement survient. Pour un EA, les plus importantes sont :
| Fonction | Déclencheur | Usage typique |
|---|---|---|
int OnInit() | chargement de l’EA ou rechargement | valider les paramètres, créer les handles, configurer CTrade |
void OnDeinit(const int reason) | arrêt ou rechargement | libérer les handles, arrêter la minuterie, nettoyer le graphique |
void OnTick() | nouveau tick sur le symbole du graphique | logique de trading |
void OnTimer() | minuterie déclenchée par EventSetTimer | tâches périodiques |
void OnTradeTransaction(...) | transaction sur le compte | réagir à une exécution |
void OnChartEvent(...) | clic, touche, objet graphique | interface utilisateur |
OnTick est spécifique aux Expert Advisors : l’événement de nouveau tick n’est envoyé qu’aux EA. Une fonction absente n’est simplement jamais appelée ; vous n’avez donc à déclarer que celles dont vous avez besoin.
5. Les fonctions utilitaires
Le reste du fichier contient vos propres fonctions : calcul du signal, calcul du lot, vérification des positions ouvertes. Gardez OnTick court et lisible en déléguant chaque tâche à une fonction nommée explicitement. Un OnTick de dix lignes qui appelle IsNewBar(), SpreadOk(), GetSignal() et OpenPosition() se relit et se teste bien mieux qu’un bloc de trois cents lignes.
Le rôle de OnInit : refuser un mauvais démarrage
OnInit peut renvoyer un code de type ENUM_INIT_RETCODE. INIT_SUCCEEDED autorise le démarrage. INIT_PARAMETERS_INCORRECT signale un jeu de paramètres invalide : en optimisation, ce jeu est ignoré et l’agent passe au suivant, ce qui évite de gaspiller du temps de calcul sur des combinaisons absurdes (période rapide supérieure à la période lente, par exemple). INIT_FAILED indique une erreur fatale : l’EA est retiré du graphique. Il vaut mieux qu’un EA refuse de démarrer que de tourner avec un handle invalide.
Le rôle de OnDeinit : laisser un environnement propre
OnDeinit reçoit un code de raison (changement de paramètres, de symbole, suppression du graphique, fermeture du terminal…). Profitez-en pour libérer les handles d’indicateurs avec IndicatorRelease, arrêter la minuterie avec EventKillTimer, effacer les commentaires et objets graphiques créés par l’EA. N’y placez pas de logique de trading : la fermeture de positions à l’arrêt doit être une décision explicite, pas un effet de bord d’un changement d’unité de temps.
Squelette complet et commenté
Le squelette ci-dessous compile tel quel. Il crée deux moyennes mobiles, configure CTrade et affiche les valeurs de la dernière bougie clôturée. La logique d’entrée est volontairement absente : elle est traitée dans la page Coder un signal d’entrée.
//+------------------------------------------------------------------+
//| Squelette d'Expert Advisor MQL5 |
//+------------------------------------------------------------------+
#property version "1.00"
#property description "Squelette d'EA : structure de référence"
#include <Trade\Trade.mqh> // classe CTrade de la bibliothèque standard
//--- paramètres d'entrée
input int InpFastPeriod = 20; // période de la moyenne rapide
input int InpSlowPeriod = 50; // période de la moyenne lente
input double InpLots = 0.10; // volume fixe (provisoire)
sinput ulong InpMagic = 260101; // identifiant de l'EA (non optimisé)
//--- variables globales : conservent leur valeur entre deux ticks
CTrade trade; // objet d'envoi des ordres
int hFast = INVALID_HANDLE; // handle de la moyenne rapide
int hSlow = INVALID_HANDLE; // handle de la moyenne lente
//+------------------------------------------------------------------+
//| Initialisation |
//+------------------------------------------------------------------+
int OnInit()
{
//--- 1. valider les paramètres
if(InpFastPeriod <= 0 || InpFastPeriod >= InpSlowPeriod)
{
Print("Paramètres incohérents : période rapide >= période lente");
return(INIT_PARAMETERS_INCORRECT);
}
//--- 2. créer les handles d'indicateurs
hFast = iMA(_Symbol, _Period, InpFastPeriod, 0, MODE_EMA, PRICE_CLOSE);
hSlow = iMA(_Symbol, _Period, InpSlowPeriod, 0, MODE_EMA, PRICE_CLOSE);
if(hFast == INVALID_HANDLE || hSlow == INVALID_HANDLE)
{
Print("Création des handles impossible, erreur ", GetLastError());
return(INIT_FAILED);
}
//--- 3. configurer l'objet de trading
trade.SetExpertMagicNumber(InpMagic);
trade.SetDeviationInPoints(10); // glissement maximal accepté
return(INIT_SUCCEEDED);
}
//+------------------------------------------------------------------+
//| Désinitialisation |
//+------------------------------------------------------------------+
void OnDeinit(const int reason)
{
if(hFast != INVALID_HANDLE) IndicatorRelease(hFast);
if(hSlow != INVALID_HANDLE) IndicatorRelease(hSlow);
Comment(""); // efface l'affichage de l'EA
Print("EA arrêté, code de raison : ", reason);
}
//+------------------------------------------------------------------+
//| Nouveau tick |
//+------------------------------------------------------------------+
void OnTick()
{
double fast[], slow[];
//--- lire la bougie clôturée (index 1) : une valeur à partir de la position 1
if(CopyBuffer(hFast, 0, 1, 1, fast) != 1) return;
if(CopyBuffer(hSlow, 0, 1, 1, slow) != 1) return;
Comment(StringFormat("MA rapide : %.5f\nMA lente : %.5f", fast[0], slow[0]));
//--- ici : filtres, signal, calcul du lot, envoi de l'ordre
}
Pièges fréquents de structure
- Créer un handle d’indicateur dans OnTick. Chaque appel à
iMAdansOnTickest inutile et coûteux : le handle se crée une fois dansOnInit, puis on lit ses valeurs avecCopyBuffer. - Ne pas vérifier le retour de CopyBuffer. Au démarrage, les données de l’indicateur peuvent ne pas être prêtes ; la fonction renvoie alors -1. Sortir de
OnTicket attendre le tick suivant est la bonne réaction. - Supposer que les variables globales survivent. Elles sont remises à leur valeur initiale à chaque rechargement. Un compteur de trades du jour stocké uniquement en mémoire repart à zéro si vous changez d’unité de temps.
- Utiliser des variables globales non initialisées. Initialisez explicitement chaque variable (
INVALID_HANDLE,0,false) pour que l’état de départ soit connu. - Mélanger plusieurs responsabilités dans OnTick. Isolez chaque étape dans une fonction : vous pourrez la tester séparément et la réutiliser dans un autre EA.
- Oublier le magic number. Sans identifiant, l’EA ne sait pas distinguer ses positions de celles ouvertes manuellement ou par un autre robot. Voir la page Le magic number.
Organisation recommandée pour un EA qui grandit
Dès que l’EA dépasse quelques centaines de lignes, déplacez les blocs indépendants dans des fichiers .mqh inclus depuis le fichier principal : un fichier pour les filtres, un pour la gestion du risque, un pour la journalisation. Le fichier .mq5 principal ne contient alors plus que les paramètres, les variables globales et les fonctions événementielles, ce qui donne une vue d’ensemble immédiate. Préfixez les paramètres (Inp) et les variables globales (g_ ou un nom explicite) pour les distinguer des variables locales au premier coup d’œil.
Questions fréquentes
Quelle est la différence entre une variable input et une variable globale ?
Une variable input est un paramètre réglable par l’utilisateur et en lecture seule dans le code. Une variable globale ordinaire est modifiable et sert à conserver l’état de l’EA entre deux appels. Les deux sont réinitialisées au rechargement de l’EA.
OnTick est-il appelé à chaque tick sans exception ?
Non. Si un tick arrive alors que l’EA traite encore le précédent, l’événement n’est pas empilé indéfiniment : un EA dont le traitement est long peut donc manquer des ticks. C’est une raison de plus pour garder OnTick rapide et de ne pas compter les ticks pour mesurer le temps.
Faut-il toujours renvoyer INIT_SUCCEEDED à la fin de OnInit ?
Oui, si tout s’est bien passé. Renvoyez INIT_PARAMETERS_INCORRECT quand les paramètres sont incohérents et INIT_FAILED quand une ressource indispensable (handle, fichier) n’a pas pu être obtenue. L’EA ne démarre pas dans ces deux cas.
Puis-je mettre plusieurs EA sur le même graphique ?
Non, un graphique n’accueille qu’un seul Expert Advisor. Pour faire tourner plusieurs EA sur un même symbole, ouvrez plusieurs graphiques et attribuez un magic number différent à chacun.
- Détecter une nouvelle bougie
- Coder un signal d’entrée
- Filtres horaires, de spread et de volatilité
- Intégrer la gestion du risque
- Limite de perte journalière
- EA multi-symboles
- Utiliser OnTimer
- Variables globales du terminal
- Sauvegarder l’état dans des fichiers
- Alertes, e-mails et notifications push
- Panneaux et boutons (CAppDialog)
- L’assistant MQL5 (MQL5 Wizard)
- Déployer un EA sur VPS
- Checklist avant mise en production
