EventLogReader.ReadEvent does not document null-returning behaviour, IDisposable info, nor give usage example

[daiplusplus]

(Creating an issue for a PR)

https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.eventing.reader.eventlogreader.readevent

None of these behaviours are documented:

• ReadEvent() and ReadEvent(TimeSpan) will return null...
  • on the first attempt to read past the end of the query results (if running a query)
  • on the first attempt to read past the last entry in the log-file on disk (if reading from a log directly).
  • subsequent attempts to read will throw an InvalidOperationException - so reading must be stopped at the first null.
• The ReadEvent method will return EventLogRecord objects instead of EventRecord - should this be documented too?
• The EventRecord type is IDisposable because it wraps an EventLogHandle, but the documentation doesn't say if the EventRecord or EventLogRecord should always be disposed inside the read-loop or not, and if it's safe to pass the EventLogRecord around or emit it in a yield break.
  • I assume it should be eagerly-disposed and not exposed to callers, so the example in my PR copies scalar data from the EventLogRecord properties into a ValueTuple and emits those instead.
• The possible exceptions System.Diagnostics.Eventing.Reader.EventLogException (and subclasses) and ``InvalidOperationException` are not documented either.

[dotnet-issue-labeler]

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

Tagging subscribers to this area: @tommcdon
See info in area-owners.md if you want to be subscribed.

Issue Details

---

(Creating an issue for a PR)

https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.eventing.reader.eventlogreader.readevent

None of these behaviours are documented:

• ReadEvent() and ReadEvent(TimeSpan) will return null...
  • on the first attempt to read past the end of the query results (if running a query)
  • on the first attempt to read past the last entry in the log-file on disk (if reading from a log directly).
  • subsequent attempts to read will throw an InvalidOperationException - so reading must be stopped at the first null.
• The ReadEvent method will return EventLogRecord objects instead of EventRecord - should this be documented too?
• The EventRecord type is IDisposable because it wraps an EventLogHandle, but the documentation doesn't say if the EventRecord or EventLogRecord should always be disposed inside the read-loop or not, and if it's safe to pass the EventLogRecord around or emit it in a yield break.
  • I assume it should be eagerly-disposed and not exposed to callers, so the example in my PR copies scalar data from the EventLogRecord properties into a ValueTuple and emits those instead.
• The possible exceptions System.Diagnostics.Eventing.Reader.EventLogException (and subclasses) and ``InvalidOperationException` are not documented either.

Author:	Jehoel
Assignees:	-
Labels:	untriaged, Pri3, area-System.Diagnostics
Milestone:	-