함수 설명서 추가

파워 쿼리는 함수의 인수에 따라 자동으로 호출 UI를 생성합니다. 기본적으로 이 UI에는 함수의 이름과 각 매개 변수에 대한 입력이 포함됩니다.

마찬가지로 매개 변수를 지정하지 않고 함수의 이름을 평가하면 함수에 대한 정보가 표시됩니다.

기본 제공 함수는 일반적으로 설명, 도구 설명 및 샘플 값과 함께 더 나은 사용자 환경을 제공한다는 것을 알 수 있습니다. 함수 형식에서 특정 메타 값을 정의하여 이 동일한 메커니즘을 활용할 수 있습니다. 이 항목에서는 파워 쿼리에서 사용되는 메타 필드와 확장에서 이를 사용하는 방법에 대해 설명합니다.

함수 형식

사용자 지정 형식 값을 정의하여 함수에 대한 설명서를 제공할 수 있습니다. 프로세스는 다음과 같습니다.

1. 각 매개 변수에 대한 형식을 정의합니다.
2. 함수의 형식을 정의합니다.
3. 형식 메타데이터 레코드에 다양한 Documentation.* 필드를 추가합니다.
4. Value.ReplaceType을 호출하여 형식을 공유 함수로 변환합니다.

M 언어 사양에서 형식 및 메타데이터 값에 대한 자세한 정보를 찾을 수 있습니다.

이 방법을 사용하면 개별 매개 변수뿐만 아니라 함수에 대한 설명 및 표시 이름을 제공할 수 있습니다. 매개 변수에 대한 샘플 값을 제공할 뿐만 아니라 미리 설정된 값 목록을 정의할 수도 있습니다(기본 텍스트 상자 컨트롤을 드롭다운으로 전환).

파워 쿼리 환경은 Value.Type, Type.FunctionParameters 및 Value.Metadata에 대한 호출의 조합을 사용하여 함수 형식의 메타 값에서 설명서를 검색합니다.

함수 설명서

다음 표에서는 함수의 메타데이터에서 설정할 수 있는 설명서 필드를 나열합니다. 모든 필드는 선택 사항입니다.

필드	Type	세부 정보
Documentation.Examples	list	함수 사용 예제가 있는 레코드 개체 목록입니다. 함수 정보의 일부로만 표시됩니다. 각 레코드에는 다음과 같은 선택적 텍스트 필드Description가 CodeResult포함되어야 합니다.
Documentation.LongDescription	text	함수 정보에 표시된 함수의 기능에 대한 전체 설명입니다.
Documentation.Name	text	함수 호출 대화 상자의 맨 위에 표시할 텍스트입니다.

매개 변수 설명서

다음 표에서는 함수 매개 변수에 대한 메타데이터에서 설정할 수 있는 설명서 필드를 나열합니다. 모든 필드는 선택 사항입니다.

필드	Type	세부 정보
Documentation.AllowedValues	list	이 매개 변수의 유효한 값 목록입니다. 이 필드를 제공하면 입력이 텍스트 상자에서 드롭다운 목록으로 변경됩니다. 따라서 사용자가 쿼리를 수동으로 편집하여 대체 값을 제공할 수 없습니다.
Documentation.FieldCaption	text	매개 변수에 사용할 표시 이름입니다.
Documentation.FieldDescription	text	표시 이름 옆에 표시할 설명입니다.
Documentation.SampleValues	list	텍스트 상자 안에 표시할 샘플 값 목록(흐리게 표시된 텍스트)입니다.
Formatting.IsMultiLine	부울 값	네이티브 쿼리에 붙여넣기 등의 여러 줄 입력을 만들 수 있습니다.
Formatting.IsCode	부울 값	일반적으로 여러 줄 입력을 사용하여 코드의 입력 필드 형식을 지정합니다. 표준 글꼴 대신 코드와 유사한 글꼴을 사용합니다.

기본 예제

다음 코드 조각(및 결과 대화 상자)은 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;

이 코드는 Power BI에서 다음 대화 상자를 생성합니다.

함수 호출

함수 정보

여러 줄 예제

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

이 코드(연결된 게시 정보 등)는 Power BI에서 다음 대화 상자를 생성합니다. 새 줄은 '#(lf)' 또는 '줄 바꿈'을 사용하여 텍스트로 표시됩니다.