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 ingesteld
true
/gewist wanneer u uw query's uitvoert. We raden u aan deze set op tetrue
houden. - 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
false
behouden. - 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.Error
en 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.Trace
en 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 GetAllPagesByNextLink
gebruiken. 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 error
wordt 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 text
en 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
Feedback
https://aka.ms/ContentUserFeedback.
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie:Feedback verzenden en weergeven voor