TripPin deel 8 - Diagnostische gegevens toevoegen

Notitie

Deze inhoud verwijst momenteel naar inhoud van een verouderde implementatie voor diagnostische gegevens in Visual Studio. De inhoud wordt in de nabije toekomst bijgewerkt om de nieuwe Power Query SDK in Visual Studio Code te behandelen.

Deze meerdelige zelfstudie bevat informatie over het maken van een nieuwe gegevensbronextensie voor Power Query. De zelfstudie is bedoeld om opeenvolgend te worden uitgevoerd. Elke les bouwt voort op de connector die in de vorige lessen is gemaakt, en voegt incrementeel nieuwe mogelijkheden toe aan uw connector.

In deze les gaat u het volgende doen:

• Meer informatie over de functie Diagnostics.Trace
• De diagnostische helperfuncties gebruiken om traceringsgegevens toe te voegen om fouten in uw connector op te sporen

Diagnostische gegevens inschakelen

Power Query-gebruikers kunnen traceringslogboekregistratie inschakelen door het selectievakje onder Opties | Diagnostische gegevens.

Zodra deze functie is ingeschakeld, zorgt elke volgende query ervoor dat de M-engine traceringsgegevens verzendt naar logboekbestanden die zich in een vaste gebruikersmap bevinden.

Bij het uitvoeren van M-query's vanuit de Power Query SDK wordt tracering ingeschakeld op projectniveau. Op de pagina met projecteigenschappen zijn er drie instellingen met betrekking tot tracering:

• Logboek wissen: als dit is ingesteld, wordt het logboek opnieuw ingesteldtrue/gewist wanneer u uw query's uitvoert. We raden u aan deze set op te truehouden.
• Enginetraceringen weergeven: met deze instelling wordt de uitvoer van ingebouwde traceringen van de M-engine bepaald. Deze traceringen zijn alleen nuttig voor leden van het Power Query-team, dus meestal wilt u deze set falsebehouden.
• Gebruikerstraceringen weergeven: deze instelling bepaalt de uitvoer van traceringsgegevens door uw connector. U wilt dit instellen op true.

Zodra deze optie is ingeschakeld, ziet u logboekvermeldingen in het venster M Query-uitvoer, onder het tabblad Logboek.

Diagnostics.Trace

De functie Diagnostics.Trace wordt gebruikt om berichten naar het traceringslogboek van de M-engine te schrijven.

Diagnostics.Trace = (traceLevel as number, message as text, value as any, optional delayed as nullable logical as any) => ...

Belangrijk

M is een functionele taal met luie evaluatie. Wanneer u de functie gebruikt Diagnostics.Trace, moet u er rekening mee houden dat de functie alleen wordt aangeroepen als de expressie waarvan deze deel uitmaakt daadwerkelijk wordt geëvalueerd. Voorbeelden hiervan vindt u verderop in deze zelfstudie.

De traceLevel parameter kan een van de volgende waarden zijn (in aflopende volgorde):

• TraceLevel.Critical
• TraceLevel.Error
• TraceLevel.Warning
• TraceLevel.Information
• TraceLevel.Verbose

Wanneer tracering is ingeschakeld, kan de gebruiker het maximale niveau van berichten selecteren dat ze willen zien. Alle traceringsberichten van dit niveau en onder worden uitgevoerd naar het logboek. Als de gebruiker bijvoorbeeld het niveau Waarschuwing selecteert, traceert u berichten van TraceLevel.Warning, TraceLevel.Erroren TraceLevel.Critical wordt deze weergegeven in de logboeken.

De message parameter is de werkelijke tekst die wordt uitgevoerd naar het traceringsbestand. De tekst bevat de value parameter alleen als u deze expliciet in de tekst opneemt.

De value parameter is wat de functie retourneert. Wanneer de delayed parameter is ingesteld op true, value is dit een nulparameterfunctie die de werkelijke waarde retourneert die u evalueert. Als delayed deze waarde is ingesteld op false, value is dit de werkelijke waarde. Hieronder vindt u een voorbeeld van hoe dit werkt.

Diagnostische gegevens gebruiken. Traceren in de TripPin-connector

Werk voor een praktisch voorbeeld van het gebruik van Diagnostics.Trace en de impact van de delayed parameter de functie van GetSchemaForEntity de TripPin-connector bij om de error uitzondering te verpakken:

GetSchemaForEntity = (entity as text) as type =>
    try
        SchemaTable{[Entity=entity]}[Type]
    otherwise
        let
            message = Text.Format("Couldn't find entity: '#{0}'", {entity})
        in
            Diagnostics.Trace(TraceLevel.Error, message, () => error message, true);

U kunt een fout afdwingen tijdens de evaluatie (voor testdoeleinden!) door een ongeldige entiteitsnaam door te geven aan de GetEntity functie. Hier wijzigt u de withData regel in de TripPinNavTable functie, waarbij u [Name] deze vervangt door "DoesNotExist".

TripPinNavTable = (url as text) as table =>
    let
        // Use our schema table as the source of top level items in the navigation tree
        entities = Table.SelectColumns(SchemaTable, {"Entity"}),
        rename = Table.RenameColumns(entities, {{"Entity", "Name"}}),
        // Add Data as a calculated column
        withData = Table.AddColumn(rename, "Data", each GetEntity(url, "DoesNotExist"), type table),
        // Add ItemKind and ItemName as fixed text values
        withItemKind = Table.AddColumn(withData, "ItemKind", each "Table", type text),
        withItemName = Table.AddColumn(withItemKind, "ItemName", each "Table", type text),
        // Indicate that the node should not be expandable
        withIsLeaf = Table.AddColumn(withItemName, "IsLeaf", each true, type logical),
        // Generate the nav table
        navTable = Table.ToNavigationTable(withIsLeaf, {"Name"}, "Name", "Data", "ItemKind", "ItemName", "IsLeaf")
    in
        navTable;

Schakel tracering in voor uw project en voer uw testquery's uit. Op het Errors tabblad ziet u de tekst van de fout die u hebt gegenereerd:

Op het Log tabblad ziet u ook hetzelfde bericht. Als u verschillende waarden voor de message en value parameters gebruikt, zijn deze anders.

Houd er ook rekening mee dat het Action veld van het logboekbericht de naam (gegevensbrontype) van uw extensie bevat (in dit geval Engine/Extension/TripPin). Dit maakt het gemakkelijker om de berichten te vinden die betrekking hebben op uw extensie wanneer er meerdere query's betrokken zijn en/of systeemtracering (mashup engine) is ingeschakeld.

Vertraagde evaluatie

Als voorbeeld van hoe de delayed parameter werkt, voert u enkele wijzigingen aan en voert u de query's opnieuw uit.

Stel eerst de delayed waarde in op false, maar laat de value parameter als volgt staan:

Diagnostics.Trace(TraceLevel.Error, message, () => error message, false);

Wanneer u de query uitvoert, krijgt u de foutmelding 'We kunnen geen waarde van het type Functie converteren naar type Type' en niet de werkelijke fout die u hebt gegenereerd. Dit komt doordat de aanroep nu een function waarde retourneert in plaats van de waarde zelf.

Verwijder vervolgens de functie uit de value parameter:

Diagnostics.Trace(TraceLevel.Error, message, error message, false);

Wanneer u de query uitvoert, ontvangt u de juiste fout, maar als u het tabblad Logboek controleert, worden er geen berichten weergegeven. Dit komt doordat het error resultaat uiteindelijk wordt gegenereerd/geëvalueerd tijdens de aanroep naar Diagnostics.Trace, zodat het bericht nooit daadwerkelijk wordt uitgevoerd.

Nu u de impact van de delayed parameter begrijpt, moet u de connector opnieuw instellen op een werkende status voordat u doorgaat.

Diagnostische helperfuncties in Diagnostics.pqm

Het bestand Diagnostics.pqm dat in dit project is opgenomen, bevat veel helperfuncties waarmee tracering eenvoudiger wordt. Zoals wordt weergegeven in de vorige zelfstudie, kunt u dit bestand opnemen in uw project (vergeet niet om de buildactie in te stellen op Compileren) en laadt u het vervolgens in het connectorbestand. De onderkant van het connectorbestand moet er nu ongeveer uitzien als het onderstaande codefragment. U kunt de verschillende functies van deze module verkennen, maar in dit voorbeeld gebruikt u alleen de Diagnostics.LogValue functies en Diagnostics.LogFailure functies.

// Diagnostics module contains multiple functions. We can take the ones we need.
Diagnostics = Extension.LoadFunction("Diagnostics.pqm");
Diagnostics.LogValue = Diagnostics[LogValue];
Diagnostics.LogFailure = Diagnostics[LogFailure];

Diagnostics.LogValue

De Diagnostics.LogValue functie lijkt veel op Diagnostics.Traceen kan worden gebruikt om de waarde uit te voeren van wat u evalueert.

Diagnostics.LogValue = (prefix as text, value as any) as any => ...

De prefix parameter wordt voorafgegaan door het logboekbericht. U zou dit gebruiken om te achterhalen welke aanroep het bericht uitvoert. De value parameter is wat de functie retourneert en wordt ook naar de trace geschreven als een tekstweergave van de M-waarde. Als value bijvoorbeeld gelijk is aan een table kolom A en B, bevat het logboek de equivalente #table weergave: #table({"A", "B"}, {{"row1 A", "row1 B"}, {"row2 A", row2 B"}})

Notitie

Het serialiseren van M-waarden naar tekst kan een dure bewerking zijn. Let op de mogelijke grootte van de waarden die u uitvoert naar de tracering.

Notitie

In de meeste Power Query-omgevingen worden traceringsberichten afgekapt tot een maximale lengte.

Als voorbeeld werkt u de TripPin.Feed functie bij om de url en argumenten te traceren die schema zijn doorgegeven aan de functie.

TripPin.Feed = (url as text, optional schema as type) as table =>
    let
        _url = Diagnostics.LogValue("Accessing url", url),
        _schema = Diagnostics.LogValue("Schema type", schema),
        //result = GetAllPagesByNextLink(url, schema)
        result = GetAllPagesByNextLink(_url, _schema)
    in
        result;

U moet de nieuwe _url waarden in _schema de aanroep naar GetAllPagesByNextLinkgebruiken. Als u de oorspronkelijke functieparameters hebt gebruikt, worden de Diagnostics.LogValue aanroepen nooit daadwerkelijk geëvalueerd, wat resulteert in geen berichten die naar de trace worden geschreven. Functioneel programmeren is leuk!

Wanneer u uw query's uitvoert, ziet u nu nieuwe berichten in het logboek.

Toegang tot URL:

Schematype:

U ziet de geserialiseerde versie van de schema parameter type, in plaats van wat u krijgt wanneer u een eenvoudige Text.FromValue methode uitvoert voor een typewaarde (wat resulteert in 'type').

Diagnostics.LogFailure

De Diagnostics.LogFailure functie kan worden gebruikt om functieaanroepen te verpakken en schrijft alleen naar de trace als de functieaanroep mislukt (dat wil gezegd, retourneert een error).

Diagnostics.LogFailure = (text as text, function as function) as any => ...

Diagnostics.LogFailure Voegt intern een try operator toe aan de function aanroep. Als de aanroep mislukt, wordt de text waarde naar de trace geschreven voordat het origineel errorwordt geretourneerd. Als de function aanroep slaagt, wordt het resultaat geretourneerd zonder iets naar de tracering te schrijven. Omdat M-fouten geen volledige stacktracering bevatten (dat wil gezegd, u ziet meestal alleen het bericht van de fout), kan dit handig zijn wanneer u wilt vaststellen waar de fout is opgetreden.

Als voorbeeld van een (slecht) voorbeeld wijzigt u de withData regel van de TripPinNavTable functie om een fout opnieuw af te dwingen:

withData = Table.AddColumn(rename, "Data", each Diagnostics.LogFailure("Error in GetEntity", () => GetEntity(url, "DoesNotExist")), type table),

In de trace vindt u het resulterende foutbericht met uw texten de oorspronkelijke foutgegevens.

Zorg ervoor dat u de functie opnieuw instelt op een werkende status voordat u doorgaat met de volgende zelfstudie.

Conclusie

In deze korte (maar belangrijke!) les hebt u geleerd hoe u de diagnostische helperfuncties kunt gebruiken om u aan te melden bij de Power Query-traceringsbestanden. Wanneer deze functies correct worden gebruikt, zijn deze functies handig bij het opsporen van fouten in uw connector.

Notitie

Als connectorontwikkelaar is het uw verantwoordelijkheid om ervoor te zorgen dat u geen gevoelige of persoonlijk identificeerbare informatie (PII) opgeeft als onderdeel van uw diagnostische logboekregistratie. U moet ook voorzichtig zijn om niet te veel traceringsgegevens uit te voeren, omdat deze een negatieve invloed kunnen hebben op de prestaties.

Volgende stappen

TripPin deel 9 - Test Verbinding maken ion