Hinzufügen der Funktionsdokumentation

Power Query generiert automatisch eine Aufrufbenutzeroberfläche für Sie basierend auf den Argumenten für Ihre Funktion. Standardmäßig enthält diese Benutzeroberfläche den Namen Ihrer Funktion und eine Eingabe für jeden Parameter.

Ebenso zeigt die Auswertung des Namens Ihrer Funktion ohne Angabe von Parametern Informationen dazu an.

Möglicherweise stellen Sie fest, dass integrierte Funktionen in der Regel eine bessere Benutzererfahrung mit Beschreibungen, QuickInfos und sogar Beispielwerten bieten. Sie können diesen Mechanismus nutzen, indem Sie bestimmte Metawerte für Ihren Funktionstyp definieren. In diesem Thema werden die Metafelder beschrieben, die von Power Query verwendet werden, und wie Sie sie in Ihren Erweiterungen verwenden können.

Funktionstypen

Sie können Dokumentation für Ihre Funktion bereitstellen, indem Sie benutzerdefinierte Typwerte definieren. Der Vorgang sieht folgendermaßen aus:

1. Definieren Sie für jeden Parameter einen Typ.
2. Definieren Sie einen Typ für Ihre Funktion.
3. Fügen Sie Ihrem Metadatendatensatz verschiedene Documentation.*-Felder hinzu.
4. Rufen Sie Value.ReplaceType auf, um den Typ ihrer freigegebenen Funktion zu schreiben.

Weitere Informationen zu Typen und Metadatenwerten finden Sie in der M-Sprachspezifikation.

Mit diesem Ansatz können Sie Beschreibungen und Anzeigenamen für Ihre Funktion sowie einzelne Parameter angeben. Sie können auch Beispielwerte für Parameter angeben sowie eine vordefinierte Liste mit Werten definieren (indem Sie das Standard-Textfeld-Steuerelement in eine Dropdownliste umwandeln).

Die Power Query-Oberfläche ruft dokumentationen aus Metawerten für den Typ Ihrer Funktion mithilfe einer Kombination aus Aufrufen von Value.Type, Type.FunctionParameters und Value.Metadata ab.

Funktionsdokumentation

In der folgenden Tabelle sind die Dokumentationsfelder aufgeführt, die in den Metadaten für Ihre Funktion festgelegt werden können. Alle Felder sind optional.

Feld	type	Details
Documentation.Examples	Liste	Liste der Datensatzobjekte mit Beispielverwendung der Funktion. Nur als Teil der Funktionsinformationen angezeigt. Jeder Datensatz sollte die folgenden optionalen Textfelder enthalten: Description, , Code und Result.
Documentation.LongDescription	Text	Vollständige Beschreibung der Funktion, die in den Funktionsinformationen angezeigt wird.
Documentation.Name	Text	Text, der über dem oberen Rand des Funktionsaufrufdialogfelds angezeigt werden soll.

Parameterdokumentation

In der folgenden Tabelle sind die Dokumentationsfelder aufgeführt, die in den Metadaten für Ihre Funktionsparameter festgelegt werden können. Alle Felder sind optional.

Feld	type	Details
Documentation.AllowedValues	Liste	Liste gültiger Werte für diesen Parameter. Wenn Sie dieses Feld angeben, wird die Eingabe aus einem Textfeld in eine Dropdownliste geändert. Beachten Sie, dass ein Benutzer die Abfrage nicht manuell bearbeiten kann, um alternative Werte zu liefern.
Documentation.FieldCaption	Text	Benutzerfreundlicher Anzeigename, der für den Parameter verwendet werden soll.
Documentation.FieldDescription	Text	Beschreibung, die neben dem Anzeigenamen angezeigt werden soll.
Documentation.SampleValues	Liste	Liste der Beispielwerte, die im Textfeld angezeigt werden sollen (als ausgeblendeter Text).
Formatting.IsMultiLine	boolean	Ermöglicht es Ihnen, eine mehrzeilige Eingabe zu erstellen, z. B. zum Einfügen in systemeigene Abfragen.
Formatting.IsCode	boolean	Formatiert das Eingabefeld für Code, häufig mit mehrzeiligen Eingaben. Verwendet eine codeähnliche Schriftart anstelle der Standardschriftart.

Einfaches Beispiel

Der folgende Codeausschnitt (und resultierende Dialogfelder) stammen aus dem HelloWorldWithDocs-Beispiel .

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

Dieser Code führt zu den folgenden Dialogfeldern in Power BI.

Funktionsaufruf

Funktionsinformationen

Mehrzeiliges Beispiel

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

Dieser Code (mit zugehörigen Veröffentlichungsinformationen usw.) führt zum folgenden Dialog in Power BI. Neue Zeilen werden im Text mit '#(lf)', oder 'Zeilenvorschub', dargestellt.