Ajout de la documentation relative aux fonctions

Power Query génère automatiquement une interface utilisateur d’appel pour vous en fonction des arguments de votre fonction. Par défaut, cette interface utilisateur contient le nom de votre fonction et une entrée pour chacun de vos paramètres.

De même, l’évaluation du nom de votre fonction, sans spécifier de paramètres, affiche des informations sur celle-ci.

Vous remarquerez que les fonctions intégrées offrent généralement une meilleure expérience utilisateur, avec des descriptions, des info-bulles et même des exemples de valeurs. Vous pouvez tirer parti de ce même mécanisme en définissant des métadonnées spécifiques sur votre type de fonction. Cette rubrique décrit les champs méta utilisés par Power Query et comment vous pouvez les utiliser dans vos extensions.

Types de fonctions

Vous pouvez fournir de la documentation pour votre fonction en définissant des valeurs de type personnalisées. Le processus se présente comme suit :

1. Définissez un type pour chaque paramètre.
2. Définissez un type pour votre fonction.
3. Ajoutez différents champs Documentation.* à votre enregistrement de métadonnées de types.
4. Appelez Value.ReplaceType pour attribuer le type à votre fonction partagée.

Vous trouverez plus d’informations sur les valeurs de types et de métadonnées dans Spécification du langage M.

L’utilisation de cette approche vous permet de fournir des descriptions et des noms d’affichage pour votre fonction, ainsi que des paramètres individuels. Vous pouvez également fournir des exemples de valeurs pour les paramètres et définir une liste prédéfinie de valeurs (transformer le contrôle de zone de texte par défaut en liste déroulante).

L’expérience Power Query récupère la documentation des métadonnées sur le type de votre fonction, à l’aide d’une combinaison d’appels à Value.Type, Type.FunctionParameters et Value.Metadata.

Documentation relative aux fonctions

Le tableau suivant répertorie les champs de documentation qui peuvent être définis dans les métadonnées de votre fonction. Tous les champs sont facultatifs.

Champ	Type	Détails
Documentation.Examples	list	Liste des objets d’enregistrement avec exemple d’utilisation de la fonction. Affichée uniquement dans les cadre des informations relatives à la fonction. Chaque enregistrement doit contenir les champs de texte facultatifs suivants : Description, Codeet Result.
Documentation.LongDescription	texte	Description complète de ce que fait la fonction, affichée dans les informations relatives à la fonction.
Documentation.Name	texte	Texte à afficher en haut de la boîte de dialogue d’appel de la fonction.

Documentation relative aux paramètres

Le tableau suivant répertorie les champs de documentation qui peuvent être définis dans les métadonnées de vos paramètres de fonction. Tous les champs sont facultatifs.

Champ	Type	Détails
Documentation.AllowedValues	list	Liste de valeurs valides pour ce paramètre. Le remplissage de ce champ transforme l’entrée d’une zone de texte en liste déroulante. Notez que cela n’empêche pas un utilisateur de modifier manuellement la requête pour fournir d’autres valeurs.
Documentation.FieldCaption	texte	Nom d’affichage convivial à utiliser pour le paramètre.
Documentation.FieldDescription	texte	Description à afficher en regard du nom d’affichage.
Documentation.SampleValues	list	Liste des exemples de valeurs à afficher (en tant que texte estompé) à l’intérieur de la zone de texte.
Formatting.IsMultiLine	booléen	Vous permet de créer une entrée multiligne, par exemple pour coller dans des requêtes natives.
Formatting.IsCode	booléen	Met en forme le champ d’entrée pour le code, généralement avec des entrées multilignes. Utilise une police de type code plutôt que la police standard.

Exemple de base

L’extrait de code suivant (et les dialogues résultants) provient de l’exemple HelloWorldWithDocs.

[DataSource.Kind="HelloWorldWithDocs", Publish="HelloWorldWithDocs.Publish"]
shared HelloWorldWithDocs.Contents = Value.ReplaceType(HelloWorldImpl, HelloWorldType);

HelloWorldType = type function (
    message as (type text meta [
        Documentation.FieldCaption = "Message",
        Documentation.FieldDescription = "Text to display",
        Documentation.SampleValues = {"Hello world", "Hola mundo"}
    ]),
    optional count as (type number meta [
        Documentation.FieldCaption = "Count",
        Documentation.FieldDescription = "Number of times to repeat the message",
        Documentation.AllowedValues = { 1, 2, 3 }
    ]))
    as table meta [
        Documentation.Name = "Hello - Name",
        Documentation.LongDescription = "Hello - Long Description",
        Documentation.Examples = {[
            Description = "Returns a table with 'Hello world' repeated 2 times",
            Code = "HelloWorldWithDocs.Contents(""Hello world"", 2)",
            Result = "#table({""Column1""}, {{""Hello world""}, {""Hello world""}})"
        ],[
            Description = "Another example, new message, new count!",
            Code = "HelloWorldWithDocs.Contents(""Goodbye"", 1)",
            Result = "#table({""Column1""}, {{""Goodbye""}})"
        ]}
    ];

HelloWorldImpl = (message as text, optional count as number) as table =>
    let
        _count = if (count <> null) then count else 5,
        listOfMessages = List.Repeat({message}, _count),
        table = Table.FromList(listOfMessages, Splitter.SplitByNothing())
    in
        table;

Ce code génère les boîtes de dialogue suivantes dans Power BI.

Invocation de la fonction

Informations sur la fonction

Exemple multiligne

[DataSource.Kind="HelloWorld", Publish="HelloWorld.Publish"]
shared HelloWorld.Contents =
    let
        HelloWorldType = type function (
            message1 as (type text meta [
                Documentation.FieldCaption = "Message 1",
                Documentation.FieldDescription = "Text to display for message 1",
                Documentation.SampleValues = {"Hello world"},
                Formatting.IsMultiLine = true,
                Formatting.IsCode = true
            ]),
            message2 as (type text meta [
                Documentation.FieldCaption = "Message 2",
                Documentation.FieldDescription = "Text to display for message 2",
                Documentation.SampleValues = {"Hola mundo"},
                Formatting.IsMultiLine = true,
                Formatting.IsCode = false
            ])) as text,
        HelloWorldFunction = (message1 as text, message2 as text) as text => message1 & message2
    in
        Value.ReplaceType(HelloWorldFunction, HelloWorldType);

Ce code (avec les informations de publication associées, et ainsi de suite) entraîne la boîte de dialogue suivante dans Power BI. Les nouvelles lignes seront représentées dans le texte avec « #(lf) » ou « line feed ».