Tilføjelse af funktionsdokumentation

Power Query genererer automatisk en aktiveringsbrugergrænseflade for dig baseret på argumenterne for din funktion. Denne brugergrænseflade indeholder som standard navnet på din funktion og et input for hver af dine parametre.

På samme måde vises der oplysninger om funktionen, når du evaluerer navnet på funktionen uden at angive parametre.

Du vil måske bemærke, at indbyggede funktioner typisk giver en bedre brugeroplevelse med beskrivelser, værktøjstip og endda eksempelværdier. Du kan drage fordel af denne samme mekanisme ved at definere specifikke metaværdier for funktionstypen. I dette emne beskrives de metafelter, der bruges af Power Query, og hvordan du kan bruge dem i dine udvidelser.

Funktionstyper

Du kan angive dokumentation til funktionen ved at definere brugerdefinerede typeværdier . Processen ser sådan ud:

1. Definer en type for hver parameter.
2. Definer en type for funktionen.
3. Føj forskellige Documentation.* felter til din type metadatapost.
4. Kald Value.ReplaceType for at tilskrive typen til din delte funktion.

Du kan finde flere oplysninger om typer og metadataværdier i M-sprogspecifikationen.

Ved hjælp af denne fremgangsmåde kan du angive beskrivelser og viste navne for din funktion samt individuelle parametre. Du kan også angive eksempelværdier for parametre samt definere en forudindstillet liste over værdier (ændre standardkontrolelementet for tekstfeltet til en rulleliste).

Power Query-oplevelsen henter dokumentation fra metaværdier for typen af din funktion ved hjælp af en kombination af kald til Value.Type, Type.FunctionParameters og Value.Metadata.

Funktionsdokumentation

I følgende tabel vises de dokumentationsfelter, der kan angives i metadataene for din funktion. Alle felter er valgfrie.

Felt	Skriv	Detaljer
Documentation.Examples	list	Liste over postobjekter med et eksempel på brug af funktionen. Vises kun som en del af funktionsoplysningerne. Hver post skal indeholde følgende valgfrie tekstfelter: Description, Codeog Result.
Documentation.LongDescription	tekst	Fuld beskrivelse af, hvad funktionen gør, vises i funktionsoplysningerne.
Documentation.Name	tekst	Tekst, der skal vises øverst i dialogboksen funktionsaktivering.

Parameterdokumentation

I følgende tabel vises de dokumentationsfelter, der kan angives i metadataene for funktionsparametrene. Alle felter er valgfrie.

Felt	Skriv	Detaljer
Documentation.AllowedValues	list	Liste over gyldige værdier for denne parameter. Hvis du angiver dette felt, ændres inputtet fra et tekstfelt til en rulleliste. Bemærk! Dette forhindrer ikke en bruger i manuelt at redigere forespørgslen for at angive alternative værdier.
Documentation.FieldCaption	tekst	Brugervenligt vist navn, der skal bruges til parameteren.
Documentation.FieldDescription	tekst	Beskrivelse, der skal vises ud for det viste navn.
Documentation.SampleValues	list	Liste over eksempelværdier, der skal vises (som udtonet tekst) i tekstfeltet.
Formatting.IsMultiLine	boolean	Giver dig mulighed for at oprette et input med flere linjer, f.eks. til indsættelse i oprindelige forespørgsler.
Formatting.IsCode	boolean	Formaterer inputfeltet for kode, ofte med input med flere linjer. Bruger en kodelignende skrifttype i stedet for standardskrifttypen.

Grundlæggende eksempel

Følgende kodestykke (og deraf følgende dialogbokse) er fra HelloWorldWithDocs-eksemplet .

[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;

Denne kode resulterer i følgende dialogbokse i Power BI.

Funktionsaktivering

Funktionsoplysninger

Eksempel på flere linjer

[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);

Denne kode (med tilknyttede publiceringsoplysninger osv.) resulterer i følgende dialog i Power BI. Nye linjer repræsenteres i tekst med '#(lf)' eller 'linjeskift'.