IDiagnosticCollector interface

The contract of a collector: an object that finds one kind of information, such as the memory or the disks, and returns it as a DiagnosticResult. A DiagnosticEngine runs objects of this type. The eleven classes of Collectors implement it, and a class of a program can implement it too.

The interface has five properties that describe the collector and two methods that collect.

Class ToolCollector
    Implements IDiagnosticCollector

    Private Property Get IDiagnosticCollector_CategoryName() As String
        Return "Tool"
    End Property

    Private Property Get IDiagnosticCollector_Description() As String
        Return "Fixed values of the program"
    End Property

    Private Property Get IDiagnosticCollector_RefreshMode() As RefreshMode
        Return RefreshMode.Static
    End Property

    Private Property Get IDiagnosticCollector_RequiresElevation() As Boolean
        Return False
    End Property

    Private Property Get IDiagnosticCollector_SupportsSummary() As Boolean
        Return True
    End Property

    Private Function IDiagnosticCollector_Collect() As DiagnosticResult(Of KeyValuePair(Of String, String))
        Dim result As DiagnosticResult(Of KeyValuePair(Of String, String))
        Set result = New DiagnosticResult(Of KeyValuePair(Of String, String))("Tool")
        result.AddItem New KeyValuePair(Of String, String)("Name", "Sample")
        result.AddItem New KeyValuePair(Of String, String)("Version", "1.2")
        Return result
    End Function

    Private Function IDiagnosticCollector_CollectSummary() As DiagnosticResult(Of KeyValuePair(Of String, String))
        Dim result As DiagnosticResult(Of KeyValuePair(Of String, String))
        Set result = New DiagnosticResult(Of KeyValuePair(Of String, String))("Tool")
        result.IsSummary = True
        result.AddItem New KeyValuePair(Of String, String)("Version", "1.2")
        Return result
    End Function
End Class

Dim engine As New DiagnosticEngine
engine.RegisterCollector New ToolCollector

Dim full As DiagnosticResult(Of KeyValuePair(Of String, String))
Dim brief As DiagnosticResult(Of KeyValuePair(Of String, String))
Set full = engine.RunCategory("Tool")
Set brief = engine.RunCategory("Tool", True)

Debug.Print full.ItemCount & " " & full.IsSummary
Debug.Print brief.ItemCount & " " & brief.IsSummary
' Output:
' 2 False
' 1 True

A collector can be run on its own, without an engine; see Calling a collector directly.

What the engine reads

The engine reads CategoryName, RefreshMode, SupportsSummary, Collect and CollectSummary. It does not read Description or RequiresElevation; they are there for the program. The category name of a collector should be the same text as the Category of the result that it returns, because a formatter prints the Category of the result, and the engine finds a collector by its CategoryName. The engine does not check that they agree.

Properties

CategoryName

The name that identifies the collector.

Syntax: collector.CategoryName As String

Read-only. The engine refuses two collectors with the same name, finds a collector by it in RunCategory and UnregisterCollector, and passes it to the events. The built-in collectors return fixed names such as Operating System and CPU Info; see Collectors.

Description

A sentence that says what the collector collects.

Syntax: collector.Description As String

Read-only. Nothing in the package reads it.

RefreshMode

How often the data of the collector changes.

Syntax: collector.RefreshMode As RefreshMode

Read-only. RunByRefreshMode selects the collectors by it.

RequiresElevation

Whether the collector needs administrator rights.

Syntax: collector.RequiresElevation As Boolean

Read-only. The engine does not read it, and does not skip a collector that returns True. All the collectors of the package return False. A program can compare it with IsElevated.

SupportsSummary

Whether the collector has a short form of its data.

Syntax: collector.SupportsSummary As Boolean

Read-only. The engine asks a collector for CollectSummary only when this is True and the run is a summary run. A collector that returns False still has to implement CollectSummary; the collectors of the package return the result of Collect from it.

Methods

Collect

Collects the data and returns it.

Syntax: collector.Collect As DiagnosticResult(Of KeyValuePair(Of String, String))

Returns a result that holds the items in the order of the report. A collector reports a failure by SetError on the result it returns, or by raising a run-time error, which the engine turns into the same kind of result, see A collector that raises an error. It returns a result, never Nothing: the engine reads the result’s Success and ItemCount, and a Nothing makes RunAll raise run-time error 91 out of the engine. The run stops at that collector, and IsRunning stays True.

CollectSummary

Collects the short form of the data.

Syntax: collector.CollectSummary As DiagnosticResult(Of KeyValuePair(Of String, String))

Returns a result with the most important items only. A collector that supports it sets IsSummary to True on the result.

See Also