PBI Documentation

18 mars 2025 · Alex Badiu

Outils externes - Leur rôle dans la documentation



Table des matières

Outils externes - Leur rôle dans la documentation
  1. DAX Studio
          1. Guider des décisions de modélisation éclairées
          2. Documenter l’évolution des performances
          3. Vérifier que les agrégations Power BI sont bien sollicitées et documenter l’impact
  2. Tabular Editor
          1. BPA - Best Practice Analyzer
          2. Règles de bonnes pratiques personnalisables
          3. Code de scripts C#
                1. Formater toutes les mesures
                2. Masquer les colonnes du côté “plusieurs”
                3. Désactiver la synthèse (Summarization Off)
                4. Contrôles de qualité des données
                5. Importer les données VPAX dans les annotations de Tabular Editor
                6. Supprimer les colonnes inutiles
                7. Copier le DAX dans la description du champ
                8. Vérifier l’heure du dernier rafraîchissement
                9. Vérifier les violations d’intégrité référentielle (RI)
                10. Table de dates étendue (par Melissa de Korte)

La documentation apporte rythme et clarté à un projet, en fixant les attentes et en traçant la voie vers les objectifs, sans ambiguïté dans les règles et les processus.

Lorsque nous finalisons la documentation, nous documentons l’excellence.


La documentation doit accompagner le développement, en aidant à identifier les améliorations tout en garantissant que notre solution est optimisée à chaque étape. Comme un chef étoilé qui vérifie et peaufine chaque assiette avant de la servir, nous devons optimiser nos rapports Power BI en supprimant les éléments inutilisés, en assurant une mise en forme et un nommage corrects, et en peaufinant chaque détail. La documentation finale doit refléter uniquement une solution développée avec minutie. Cette attention portée au détail tout au long du processus est ce qui distingue les meilleurs professionnels Power BI.

Cette approche met en avant le fait que la documentation sert trois objectifs :

  • servir d’outil de contrôle qualité pendant le développement
  • constituer une preuve d’excellence dans le produit final.
  • servir de point de départ pour évaluer et apporter de futures modifications

Pour atteindre efficacement ces objectifs, des outils externes complémentaires sont essentiels. Dans le numéro 8 de cette semaine, nous présenterons un aperçu de deux outils externes qui peuvent aider à rationaliser la documentation et à accélérer le développement de manière professionnelle.

Sans plus attendre, entrons dans le vif du sujet :

1. DAX Studio - View Model

DAX Studio est un outil puissant, open-source et gratuit, spécialement conçu pour interroger et optimiser le DAX. C’est un incontournable pour les professionnels Power BI, en particulier ceux qui réalisent des tâches d’optimisation.

DAX Studio a la capacité d’analyser votre modèle de données et de rendre compte de l’utilisation de la mémoire. Cela peut s’avérer extrêmement utile lors du réglage des performances, car plus votre modèle de données nécessite de mémoire, plus son traitement et ses requêtes sont lents.

S’il est clair que DAX Studio est « inconturnable » (incontournable) pour un développeur professionnel, quels avantages spécifiques cet outil apporte-t-il à la documentation ?

Avantages clés :

1. Guider des décisions de modélisation éclairées

  • Les métriques de modèle de DAX Studio fournissent des informations détaillées sur l’utilisation de la mémoire, la taille des tables et les détails des colonnes. Cela permet d’identifier les éléments de votre modèle qui consomment le plus de ressources, vous permettant de prendre des décisions éclairées sur ce qu’il faut supprimer ou organiser différemment. Cette visibilité technique crée une base pour des conversations essentielles entre développeurs et utilisateurs finaux au sujet des compromis, car tout, dans un modèle, a un coût. Ces discussions aident à établir qu’un modèle sémantique NE doit PAS chercher à répondre à toutes les questions possibles dans un rapport, mais plutôt se concentrer sur les besoins métier clés. Sur le plan documentaire, ces informations sont précieuses non seulement à intégrer dans votre documentation finale, mais aussi comme point de départ lors de la phase d’exploration initiale du projet.
  • En documentant ces métriques et le raisonnement derrière les choix de modélisation, vous créez un référentiel précieux qui :
  1. Montre l’intentionnalité derrière chaque inclusion ou exclusion
  2. Fournit du contexte aux futurs mainteneurs sur les raisons de certains compromis
  3. Établit une justification claire des limites de portée du modèle
  4. Crée de la transparence autour des considérations de performance

Cette approche de la documentation transforme ce qui pourrait être perçu comme des limitations techniques en preuve de décisions de conception réfléchies, ce qui est particulièrement précieux pour justifier les contraintes du modèle auprès des parties prenantes qui pourraient sinon demander des capacités toujours plus étendues sans en comprendre les coûts associés.

2. Documenter l’évolution des performances

  • DAX Studio excelle dans le suivi des évolutions de performance dans le temps. Suivez ces étapes pour établir un processus de benchmarking fiable :
  1. Créer un protocole de test standardisé :
    • Documenter des étapes de navigation précises dans un ordre cohérent
    • Inclure les filtres, la navigation entre pages, les actions de drill-through et les éléments interactifs
    • S’assurer que le protocole peut être reproduit précisément à chaque fois
  2. Exécuter le test de performance :
    • S’assurer que l’environnement de test dispose d’un volume et d’une variété de données représentatifs de la production (sinon, les tests de performance ne décrivent que le processus de développement et ne peuvent pas être utilisés pour évaluer les exigences de performance en production).
    • Ouvrir une nouvelle instance de Power BI Desktop
    • Partir d’une page vierge pour éviter les données mises en cache
    • Activer l’Analyseur de performances
    • Suivre systématiquement votre protocole de test documenté
  3. Capturer et analyser les résultats :
    • Exporter les résultats de l’Analyseur de performances au format JSON
    • Importer ces données dans DAX Studio via « Load Perf Data »
    • Générer des métriques de performance concrètes servant de preuves
    • Établir ces résultats comme référence pour les comparaisons futures
  4. Intégrer cela à votre flux de travail :
    • Faire des tests de performance une exigence obligatoire pour tout travail de développement
    • Comparer les nouvelles versions au benchmark établi
    • Valider l’impact avec les clients avant de déployer en production

En mettant en œuvre cette approche systématique des tests de performance, vous transformez des perceptions subjectives en mesures objectives. Lorsque les clients demandent des fonctionnalités complexes, vous disposerez de données concrètes pour les challenger et démontrer les implications sur la performance. Cela vous positionne comme un conseiller de confiance qui équilibre fonctionnalité et performance, plutôt que comme un « constructeur de rapports » qui se contente de faire ce qu’on lui demande. Cette approche fondée sur des preuves vous permet, en tant que développeur, de prendre des décisions éclairées et de proposer aux clients des solutions véritablement optimisées.

Pasted image 20250314164229

Pasted image 20250314164512



[!TIP] Veillez à renommer d’abord chaque élément de la page pour plus de clarté.

[!TIP] Intégrez ces données de performance dans un rapport Power BI dédié afin de suivre les dates de test et les versions/modifications du modèle, et de conserver une visibilité sur les tendances de performance. Envisagez de développer des modèles standardisés pour suivre l’évolution des performances sur l’ensemble de vos rapports.

3. Vérifier que les agrégations Power BI sont bien sollicitées et documenter l’impact

DAX Studio est essentiel pour confirmer que vos agrégations Power BI sont réellement utilisées et apportent des gains de performance. Sans cette vérification, l’effort consacré à la création des agrégations pourrait être vain.

Avec DAX Studio, vous pouvez :

  • Confirmer quelles requêtes utilisent quelles tables d’agrégation par rapport aux tables détaillées
  • Créer des comparaisons de performance avant/après montrant des améliorations tangibles
  • Documenter précisément quelles mesures et combinaisons de filtres bénéficient des agrégations
  • Suivre quels scénarios utilisateurs spécifiques sont optimisés

Cette documentation fournit une preuve concrète que votre stratégie d’agrégation fonctionne comme prévu et apporte les gains de performance attendus. Elle transforme une implémentation technique en preuve mesurable et documentée d’optimisation que les parties prenantes peuvent comprendre.

2. Tabular Editor

Tabular Editor est largement considéré comme l’outil externe le plus essentiel parmi les professionnels Power BI. Bien que ses avantages soient suffisamment nombreux pour constituer une série entière, cet article se concentre spécifiquement sur la manière dont, selon moi, Tabular Editor améliore les processus de documentation.

Avantages clés :

1. BPA : Best Practice Analyzer

BPA analyse votre modèle par rapport à des règles de bonnes pratiques courantes, identifiant rapidement tout écart. Il vous permet de :

  • Évaluer la qualité du modèle en quelques secondes
  • Générer des rapports de qualité détaillés
  • Documenter les axes d’amélioration
  • Suivre la conformité dans le temps

Vous pouvez également exporter ces règles pour créer un fichier d’accompagnement démontrant que votre développement respecte les bonnes pratiques. Cela aide les clients non experts à gagner confiance en votre travail.

À l’aide du script C# ci-dessous, vous pouvez exporter les données vers un fichier Excel et documenter l’information.

using TabularEditor.BestPracticeAnalyzer;
  
var bpa = new Analyzer();
bpa.SetModel(Model);
  
var sb = new System.Text.StringBuilder();
string newline = Environment.NewLine;
  
sb.Append("RuleCategory" + '\t' + "RuleName" + '\t' + "ObjectName" + '\t' + "ObjectType" + '\t' + "RuleSeverity" + '\t' + "HasFixExpression" + '\t' + "RuleDescription" + newline);
  
foreach (var a in bpa.AnalyzeAll().ToList())
{
    sb.Append(a.Rule.Category + '\t' + a.RuleName + '\t' + a.ObjectName + '\t' + a.ObjectType + '\t' + a.Rule.Severity + '\t' + a.CanFix + '\t' + a.Rule.Description + newline);
}
  
sb.Output();
Pasted image 20250315164412

Pour charger ces règles dans Tabular Editor (afin qu’elles puissent être appliquées à vos rapports), suivez ces étapes :

Charger les règles
  1. Téléchargez et installez Tabular Editor.
  2. Ouvrez Tabular Editor et exécutez le code suivant dans la fenêtre Advanced Scripting. *
  3. Copiez/collez le code suivant et cliquez sur Play

System.Net.WebClient w = new System.Net.WebClient(); string path = System.Environment.GetFolderPath(System.Environment.SpecialFolder.LocalApplicationData); string url = "https://raw.githubusercontent.com/microsoft/Analysis-Services/master/BestPracticeRules/BPARules.json"; string downloadLoc = path+@"\TabularEditor\BPARules.json"; w.DownloadFile(url, downloadLoc);

  1. Fermez et rouvrez Tabular Editor
Pasted image 20250315164412

Pasted image 20240726170929

Source : Best practice rules to improve your model’s performance | Microsoft Power BI Blog | Microsoft Power BI

2. Règles de bonnes pratiques personnalisables

BPA se distingue par sa flexibilité. Vous pouvez :

  • Créer des règles personnalisées adaptées à votre organisation
  • Documenter des exigences d’implémentation spécifiques
  • Tirer parti des ressources de la communauté si le scripting C# n’est pas votre point fort
  • Importer des règles créées par la communauté pour enrichir la documentation

La communauté Power BI contribue activement à ces ressources. Des experts comme Matt Allington, Kurt Buhler, Melissa de Korte, Brian Julius, Michael Kovalsky, Reid Havens et d’autres ont partagé des extraits précieux. John Kerski, par exemple, a publié sur son GitHub des règles personnalisées spécifiques à Power Query, à la suite de retours reçus sur LinkedIn. Cela permet non seulement de documenter votre rapport, mais aussi de garantir le respect des bonnes pratiques et d’accélérer le développement. Post LinkedIn

Charger les règles

Rendez-vous sur le GitHub de John Kerski, allez sur PQ_Rules.json, cliquez sur Raw et copiez le lien Pasted image 20250315170325

Allez dans Tabular Editor (2 ou 3) - Tools / Manage BPA rules, puis Include Rule File from URL Pasted image 20250315165831

Collez le lien que vous avez copié depuis le fichier raw. Pasted image 20240726170929

Vous pouvez maintenant voir les règles Pasted image 20250315165940

Ces règles BPA constituent non seulement une excellente ressource pour documenter vos rapports et démontrer le respect des bonnes pratiques, mais elles vous poussent également à améliorer votre documentation intégrée à l’outil.

Pasted image 20250315170118

3. Code de scripts C#

Voici les 10 scripts C# que j’ai trouvés les plus utiles pour documenter des rapports Power BI. Ce sont des outils éprouvés qui accélèrent considérablement le développement et améliorent la documentation. Ces scripts apportent des bénéfices immédiats et tangibles à votre travail ; n’hésitez donc pas à les enregistrer, à les expérimenter et à les intégrer si vous les trouvez utiles.

1. Formater toutes les mesures
Model.AllMeasures.FormatDax();

Vous pouvez trouver le script C# ici

2. Masquer les colonnes du côté “plusieurs”
/*
 * Title: Hide columns on the many side of a relationship  
 *
 * Author: Matt Allington, https://exceleratorbi.com.au  
 *
 * it is dangerous to use columns on the many side of a relationship as it can 
 * produce unexpected results, so it is a best practice to hide these columns
 * to discourage their use in reports.
 */

// Hide all columns on many side of a join
foreach (var r in Model.Relationships)
{ // hide all columns on the many side of a join
    var c = r.FromColumn.Name;
    var t = r.FromTable.Name;
    Model.Tables[t].Columns[c].IsHidden = true;
}

Vous pouvez trouver le script C# ici

3. Désactiver la synthèse (Summarization Off)
foreach(var c in Model.AllColumns)
{
    c.SummarizeBy = AggregateFunction.None;
}

Vous pouvez trouver le script C# ici

4. Contrôles de qualité des données

Vous pouvez trouver le script C# ici

5. Importer les données VPAX dans les annotations de Tabular Editor

Import VPAX Data into Tabular Editor

Ce code permet d’ajouter des annotations dans Tabular Editor à partir des informations d’un fichier Vertipaq Analyzer (VPAX). Et désormais, vous pouvez vérifier de manière globale l’intégrité de votre modèle via des règles BPA qui font référence à ces annotations. Vous pouvez trouver le script C# ici

6. Supprimer les colonnes inutiles

Vous pouvez trouver le script C# ici

7. Copier le DAX dans la description du champ
/*
 * Title: Copy DAX Expression into the measure's description field.
 * 
 * Author: Reid Havens, https://www.havensconsulting.net/ 
 * 
 * This script, when executed, will loop through all the measures in the model and
 * copy the DAX epression into the field's description for documentation purposes.
 */

foreach (var m in Model.AllMeasures) {
  m.Description = m.Expression;
}

Vous pouvez trouver le script C# ici

Pasted image 20250315172622

8. Vérifier l’heure du dernier rafraîchissement
//https://data-goblins.com/power-bi/te-dmv-scripts
/////////////////////////////////////////////////////////////////////////////////////////////
//
// Evaluates a DMV to determine the last time the model was processed (refreshed)
//
// Original method from Marco Russo https://www.sqlbi.com/articles/last-process-date-in-ssas-tabular/
//
/////////////////////////////////////////////////////////////////////////////////////////////

// Query to be evaluated
string _dmv = "SELECT TOP 1 [LAST_DATA_UPDATE] FROM $SYSTEM.MDSCHEMA_CUBES";

// Evaluate the query
using(var daxReader = ExecuteReader(_dmv))
{
    // Read the results
    while(daxReader.Read())
    
    {
        var rowValues = new object[daxReader.FieldCount];
        daxReader.GetValues(rowValues);
        var row = rowValues.Select(v => v == null ? "" : v);

        // Convert the scalar value to a string
        string _processdate = row.ElementAt(0).ToString();
        Info ( "The model was last processed at " + _processdate);
    }

    // Close the reader
    daxReader.Close();

}

Vous pouvez trouver le script C# ici

Pasted image 20250315173324

9. Vérifier les violations d’intégrité référentielle (RI)

Vous pouvez trouver le script C# ici

Pasted image 20250315173433

10. Table de dates étendue, par Melissa de Korte

Extended Date table M function | Creates an ISO-8601 type calendar

💬 Discutons-en :

  • Quel est votre outil de prédilection pour la documentation Power BI ?
  • Quel a été le plus grand défi que vous ayez rencontré pour maintenir des rapports bien documentés ?

Partagez vos réflexions dans le post LinkedIn : nous serions ravis de poursuivre la discussion ! Post LinkedIn : #Issue 8 - External Tools - Their Role in Documentation

Voir la source (anglais) sur GitHub