Ajouter une documentation de fonction

Power Query génère automatiquement une interface utilisateur d’appel 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 peut-être 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 valeurs meta spécifiques sur votre type de fonction. Cet article décrit les champs meta utilisés Power Query et la façon dont vous pouvez les utiliser dans vos extensions.

Types de fonction

Vous pouvez fournir de la documentation pour votre fonction en définissant des valeurs de type personnalisées. Le processus ressemble à ceci :

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

Pour plus d’informations sur les types et les valeurs de métadonnées, consultez la spécification du langage M.

À l’aide de cette approche, vous pouvez fournir des descriptions et des noms d’affichage pour votre fonction et 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 de la fonction

Le tableau suivant répertorie les champs de documentation que vous pouvez définir dans les métadonnées de votre fonction. Tous les champs sont facultatifs.

Terrain	Type	Détails
Documentation.Exemples	list	Liste des objets d’enregistrement avec exemple d’utilisation de la fonction. Uniquement affiché dans le cadre des informations de 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 de fonction.
Documentation.Nom	texte	Texte à afficher en haut de la boîte de dialogue d’appel de fonction.

Documentation sur les paramètres

Le tableau suivant répertorie les champs de documentation que vous pouvez définir dans les métadonnées de vos paramètres de fonction. Tous les champs sont facultatifs.

Terrain	Type	Détails
Documentation.AllowedValues	list	Liste des valeurs valides pour ce paramètre. Le fait de renseigner ce champ remplace la zone de texte par une liste déroulante. Notez que cette modification n’empêche pas un utilisateur de modifier manuellement la requête pour fournir d’autres valeurs.
Légende de champ de documentation	texte	Nom d'affichage convivial à utiliser pour le paramètre.
Documentation.FieldDescription	texte	Description à afficher en regard du nom d’affichage.
Documentation.ExemplesValeurs	list	Liste d’exemples de valeurs à afficher (en tant que texte décoloré) à l’intérieur de la zone de texte.
Formatting.IsMultiLine	boolean	Vous permet de créer une entrée multiligne, par exemple pour coller dans des requêtes natives.
Formatting.IsCode	boolean	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 proviennent 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 crée les dialogues suivants dans Power BI.

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) crée la boîte de dialogue suivante dans Power BI. Les nouvelles lignes apparaissent dans le texte sous la forme #(lf), ou line feed.