Tilføj funktionsdokumentation

Power Query genererer automatisk et kald UI baseret på argumenterne for din funktion. Som standard indeholder dette UI navnet på din funktion og et input til hver af dine parametre.

På samme måde viser evaluering af navnet på din funktion uden at specificere parametre information om den.

Du vil måske bemærke, at indbyggede funktioner typisk giver en bedre brugeroplevelse med beskrivelser, tooltips og endda prøveværdier. Du kan udnytte denne samme mekanisme ved at definere specifikke metaværdier på din funktionstype. Denne artikel beskriver de metafelter, som Power Query bruger, og hvordan du kan udnytte dem i dine udvidelser.

Funktionstyper

Du kan levere dokumentation for din funktion ved at definere brugerdefinerede typeværdier . Processen ser sådan ud:

1. Definér en type for hver parameter.
2. Definér en type for din funktion.
3. Tilføj forskellige Documentation.* felter til din types metadata-post.
4. Kald Value.ReplaceType for at tildele typen til din delte funktion.

For mere information om typer og metadataværdier, se M-sprogspecifikationen.

Ved at bruge denne tilgang kan du levere beskrivelser og visningsnavne for din funktion og dine individuelle parametre. Du kan også levere prøveværdier for parametre og definere en forudindstillet liste af værdier (ved at gøre standardtekstbokskontrollen til en dropdown).

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

Funktionsdokumentation

Følgende tabel viser de dokumentationsfelter, du kan sætte i metadataene for din funktion. Alle felter er valgfrie.

Parameterdokumentation

Følgende tabel viser de dokumentationsfelter, du kan sætte i metadataene for dine funktionsparametre. Alle felter er valgfrie.

Grundlæggende eksempel

Følgende kodeuddrag og de resulterende dialoger stammer 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 opretter følgende dialoger i Power BI.

Funktionskald

Funktionsinfo

Flerlinje-eksempel

[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 tilhørende publiceringsinformation osv.) skaber følgende dialog i Power BI. Nye linjer optræder i tekst som #(lf), eller line feed.