Lägga till funktionsdokumentation

Power Query genererar automatiskt ett användargränssnitt för anrop åt dig baserat på argumenten för din funktion. Som standard innehåller det här användargränssnittet namnet på din funktion och en indata för var och en av dina parametrar.

På samma sätt visar utvärdering av namnet på din funktion, utan att ange parametrar, information om den.

Du kanske märker att inbyggda funktioner vanligtvis ger en bättre användarupplevelse, med beskrivningar, knappbeskrivningar och till och med exempelvärden. Du kan dra nytta av samma mekanism genom att definiera specifika metavärden för din funktionstyp. Det här avsnittet beskriver de metafält som används av Power Query och hur du kan använda dem i dina tillägg.

Funktionstyper

Du kan ange dokumentation för din funktion genom att definiera anpassade typvärden . Processen ser ut så här:

1. Definiera en typ för varje parameter.
2. Definiera en typ för din funktion.
3. Lägg till olika Documentation.* fält i metadataposten för dina typer.
4. Anropa Value.ReplaceType för att tillskriva typen till din delade funktion.

Mer information om typer och metadatavärden finns i M-språkspecifikationen.

Med den här metoden kan du ange beskrivningar och visningsnamn för din funktion samt enskilda parametrar. Du kan också ange exempelvärden för parametrar, samt definiera en förinställd lista med värden (vilket gör standardkontrollen för textrutor till en listruta).

Power Query-upplevelsen hämtar dokumentation från metavärden på typen av funktion med hjälp av en kombination av anrop till Value.Type, Type.FunctionParameters och Value.Metadata.

Funktionsdokumentation

I följande tabell visas de dokumentationsfält som kan anges i metadata för din funktion. Alla fält är valfria.

Fält	Typ	Details
Documentation.Examples	lista	Lista över postobjekt med exempel på användning av funktionen. Visas endast som en del av funktionsinformationen. Varje post ska innehålla följande valfria textfält: Description, Codeoch Result.
Documentation.LongDescription	text	Fullständig beskrivning av vad funktionen gör, som visas i funktionsinformationen.
Documentation.Name	text	Text som ska visas överst i dialogrutan funktionsanrop.

Parameterdokumentation

I följande tabell visas de dokumentationsfält som kan anges i metadata för dina funktionsparametrar. Alla fält är valfria.

Fält	Typ	Details
Documentation.AllowedValues	lista	Lista över giltiga värden för den här parametern. Om du anger det här fältet ändras indata från en textruta till en listruta. Observera att detta inte hindrar en användare från att redigera frågan manuellt för att ange alternativa värden.
Documentation.FieldCaption	text	Eget visningsnamn som ska användas för parametern.
Documentation.FieldDescription	text	Beskrivning som ska visas bredvid visningsnamnet.
Documentation.SampleValues	lista	Lista över exempelvärden som ska visas (som blekt text) i textrutan.
Formatting.IsMultiLine	boolean	Gör att du kan skapa indata med flera rader, till exempel för att klistra in interna frågor.
Formatering.IsCode	boolean	Formaterar indatafältet för kod, vanligtvis med indata med flera rader. Använder ett kodliknande teckensnitt i stället för standardteckensnittet.

Grundläggande exempel

Följande kodfragment (och resulterande dialogrutor) kommer från HelloWorldWithDocs-exemplet .

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

Den här koden resulterar i följande dialogrutor i Power BI.

Funktionsanrop

Funktionsinformation

Exempel på flera rader

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

Den här koden (med tillhörande publiceringsinformation och så vidare) resulterar i följande dialog i Power BI. Nya rader representeras i text med '#(lf)' eller 'line feed'.