You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+4-4Lines changed: 4 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@
7
7
The Microsoft Performance Toolkit is a collection of cross-platform tools developers can use to create
8
8
and extend performance analysis applications. It serves as the runtime of the [Windows Performance Analyzer](https://docs.microsoft.com/en-us/windows-hardware/test/wpt/windows-performance-analyzer),
9
9
a Windows program included in the [Windows Performance Toolkit](https://docs.microsoft.com/en-us/windows-hardware/test/wpt/).
10
-
By using the Microsoft Performance Toolkit SDK, Windows Performance Anlazyer - or any performance analysis application -
10
+
By using the Microsoft Performance Toolkit SDK, Windows Performance Analyzer - or any performance analysis application -
11
11
can be configured to process and display performance data from arbitrary sources.
12
12
13
13
The Microsoft Performance Toolkit SDK provides two key functionalities:
These two functionalities are not mutually exclusive, and plugins may access data in another plugin's (or, commonly, its own)
20
20
data-processing pipeline when creating tables for a given data source.
21
21
22
-
For help with getting started and developing SDK plugins, refer to our [documentation](./documentation/Overview.md).
22
+
For help with getting started and developing SDK plugins, refer to our [documentation](./documentation/README.md).
23
23
24
24
## In this Repository
25
25
*`devel-template`: a work-in-progress .NET template for creating SDK plugins
@@ -44,11 +44,11 @@ For help with getting started and developing SDK plugins, refer to our [document
44
44
45
45
This repository tracks which versions of the SDK are compatibile with certain SDK drivers such as Windows Performance Analyzer. This information can be used to determine which version of an SDK driver should be used when loading plugins compiled against a specific SDK version.
46
46
47
-
This information is listed in the [known SDK driver compatibility lists](./documentation/Known-SDK-Driver-Compatibility/Overview.md) document.
47
+
This information is listed in the [known SDK driver compatibility lists](./documentation/Known-SDK-Driver-Compatibility/README.md) document.
48
48
49
49
## Getting Started
50
50
51
-
Refer to the [documentation folder](./documentation/Overview.md) for help with creating SDK plugins.
51
+
Refer to the [documentation folder](./documentation/README.md) for help with creating SDK plugins.
Copy file name to clipboardExpand all lines: documentation/Glossary.md
+4-2Lines changed: 4 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -109,6 +109,8 @@ If the "State" column above is a [Pivot Column](#pivot-column), the 5 rows would
109
109
110
110
NOTE: the SDK has no understanding of Pivot Tables. Tables created by a plugin are purely "flat" tables - i.e. tables similar the first one above. It is up to programs like [Windows Performance Analyzer](#windows-performance-analyzer) to use pivot information in a [Table Configuration](#tableconfiguration) to present a plugin's Table as a Pivot Table.
111
111
112
+
See also: [Wikipedia Pivot Tables](https://en.wikipedia.org/wiki/Pivot_table).
113
+
112
114
## Plugin
113
115
114
116
A collection of one-or-more [ProcessingSources](#processingsource) that collectively create zero-or-more [Tables](#table) and consist of zero-or-more [DataCookers](#datacooker).
@@ -141,11 +143,11 @@ A [Table](#table) variant that cannot participate in a [Processing Pipeline](#pr
141
143
142
144
## SourceDataCooker
143
145
144
-
A [DataCooker](#datacooker) that receives input from a specific[SourceParser](#sourceparser). A SourceDataCooker may also receive input from other DataCookers of the same SourceParser.
146
+
A [DataCooker](#datacooker) that receives input from an associated[SourceParser](#sourceparser). A SourceDataCooker may also receive input from other SourceDataCookers enabled on the same SourceParser.
145
147
146
148
## SourceParser
147
149
148
-
An object that a [CustomDataProcessor](#customdataprocessor)typically tasks with parsing a [DataSource](#datasource) into individual records. The records that a SourceParser emits typically begin a [Processing Pipeline](#processing-pipeline), wherein [DataCookers](#datacooker) further process data to be consumed by [Tables](#table).
150
+
An object that a [CustomDataProcessor](#customdataprocessor) tasks with parsing a [DataSource](#datasource) into individual records. The records that a SourceParser emits begin a [Processing Pipeline](#processing-pipeline), wherein [DataCookers](#datacooker) further process data to be consumed by [Tables](#table).
Copy file name to clipboardExpand all lines: documentation/README.md
+9-7Lines changed: 9 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -4,14 +4,19 @@ These plugins can be used by performance analysis applications that use the SDK
4
4
5
5
This folder contains instructions for developing SDK plugins and utilizing the SDK's various features.
6
6
7
+
# Quick Start
8
+
Refer to [Creating your first plugin](Using-the-SDK/Creating-your-plugin.md) to jump in quickly.
9
+
10
+
> ⚠️ Note: We recommend following the [Recommended Reading Order](#recommended-reading-order).
11
+
7
12
# Glossary
8
13
9
14
For quick definitions/examples of terms and concepts, refer to the [Glossary](./Glossary.md).
10
15
11
16
# Requirements
12
17
The following are required in order to develop an SDK plugin:
13
18
*[NuGet](https://www.nuget.org/downloads)
14
-
*[.NET Standard 2.0](https://dotnet.microsoft.com/download/visual-studio-sdks)
19
+
*[.NET Standard 2.0](https://dotnet.microsoft.com/download/visual-studio-sdks) or a [compatible version](https://docs.microsoft.com/en-us/dotnet/standard/net-standard?tabs=net-standard-1-0#tabpanel_1_net-standard-2-0)
15
20
* A text editor (for editing your source code)
16
21
17
22
It is recommended to use [Visual Studio](https://visualstudio.microsoft.com/downloads/) to develop an SDK plugin since it satisfies all three requirements. Future documentation assumes the use of Visual Studio, but the instructions may be adapted for other editors/IDEs.
@@ -21,12 +26,9 @@ The SDK is published as a NuGet package under the name [Microsoft.Performance.SD
21
26
Since it is hosted on [NuGet.org](https://www.nuget.org/), it can be added to a `csproj` with no additional configuration by using
22
27
the Visual Studio NuGet Package Manager, `dotnet.exe`, or `nuget.exe`.
23
28
24
-
# Creating A Plugin
25
-
Refer to [Creating your first plugin](Using-the-SDK/Creating-your-plugin.md)
26
-
27
29
# Recommended Reading Order
28
30
To best understand how the SDK works and how to develop SDK plugins, it is recommended to read documentation in the following order:
29
-
1)[Architecture/Overview](./Architecture/Overview.md) to understand at a high level the various systems the SDK provides
30
-
2)[Architecture/The Data-Processing Pipeline](./Architecture/The-Data-Processing-Pipeline.md) to understand how to systematically process data that
31
+
1.[Architecture/Overview](./Architecture/README.md) to understand at a high level the various systems the SDK provides
32
+
2.[Architecture/The Data-Processing Pipeline](./Architecture/The-Data-Processing-Pipeline.md) to understand how to systematically process data that
31
33
can be used by tables
32
-
3)[Creating your first plugin](Using-the-SDK/Creating-your-plugin.md) to learn how to create an SDK plugin
34
+
3.[Creating your first plugin](Using-the-SDK/Creating-your-plugin.md) to learn how to create an SDK plugin
Copy file name to clipboardExpand all lines: documentation/Using-the-SDK/Building-a-table.md
+40-21Lines changed: 40 additions & 21 deletions
Original file line number
Diff line number
Diff line change
@@ -1,21 +1,38 @@
1
1
# Building a Table
2
2
3
-
Table construction happens by interacting with an instance of an `ITableBuilder`. Broadly, `Tables` consist of `TableConfigurations` and Columns. Columns can be further broken down into `ColumnConfigurations` and `Projections`. An `ITableBuilder` has methods to add both Columns and `TableConfigurations`.
4
-
5
-
*[Column](#column)
6
-
*[ColumnConfiguration](#columnconfiguration)
7
-
*[Projection](#projection)
8
-
*[Combining ColumnConfiguration and Projections](#combining-columnconfiguration-and-projections)
9
-
*[TableConfiguration](#tableconfiguration)
3
+
Table construction happens by interacting with an instance of an `ITableBuilder`. Broadly, `Tables` consist of `TableConfigurations` and columns, which are composed of `ColumnConfigurations` and `Projections`.
4
+
5
+
*[Adding Columns](#adding-columns)
6
+
*[Setting the table's row count](#setting-the-tables-row-count)
A column is a conceptual pair (`ColumnConfiguration`, `Projection`) that defines data inside a table. Every column inside of a table must be composed of the same number of rows. Because of this, before we can add columns to the table, we must specify the table's row count.
16
+
17
+
Adding columns to a table can therefore be broken down into the following 4 steps:
18
+
1. Setting the table's row count
19
+
2. Declaring column configurations
20
+
3. Defining column projections
21
+
4. Adding columns to the table
13
22
14
-
A column is a conceptual (`ColumnConfiguration`, `Projection`) pair that defines data inside a [Table](#table).
23
+
### Setting the table's row count
15
24
16
-
### ColumnConfiguration
25
+
To add columns to our table, we first must get an instance of `ITableBuilderWithRowCount`. This is accomplished by calling `ITableBuilder.SetRowCount`. For example, if we have an array of data where each element will become a row in the final table, we can do
A `ColumnConfiguration` contains metadata information about a column. For example, it contains the column's name and description, along with `UIHints` that help GUI viewers know how to render the column.
31
+
> ❗Important: Every projection in the table must support the table's established row count.
32
+
33
+
### Declaring column configurations
34
+
35
+
Each column in a table must have an associated `ColumnConfiguration`. A `ColumnConfiguration` contains metadata information about a column. For example, it contains the column's name and description, along with `UIHints` that help GUI-based SDK drivers render the column.
19
36
20
37
Typically, `ColumnConfigurations` are stored as `static` fields on the `Table` class for the `Table` being built. For example,
21
38
@@ -43,7 +60,8 @@ public sealed class WordTable
43
60
}
44
61
```
45
62
46
-
### Projection
63
+
### Defining column projections
64
+
47
65
48
66
A column's `Projection` is a function that maps a row index for a column to a piece of data. Projections are normally constructed at runtime by a `Build` method, since they depend on the data inside the final table. The SDK offers many helper methods for constructing `Projections`, such as:
49
67
*`Projection.Index(IReadOnlyList<T> data)`, which projects a column index `i` to `data[i]`
@@ -58,18 +76,18 @@ var lineNumberProjection = baseProjection.Compose(lineItem => lineItem.LineNumbe
If we have the `ColumnConfigurations` and `Projections` above, we can add them to the table we're building by calling `ITableBuilder.AddColumn`:
81
+
With the `ColumnConfigurations` and `Projections` above, we can add them to the table we're building by calling `AddColumn` on the `tableBuilderWithRowCount` created above:
Note that _every_ column a table provides must be added through a call to `ITableBuilder.AddColumn`, even if they're not used in a `TableConfiguration` (see below).
88
+
Note that _every_ column a table provides must be added through a call to `ITableBuilderWithRowCount.AddColumn`, even if they're not used in a `TableConfiguration` (see below).
71
89
72
-
## TableConfiguration
90
+
## Adding TableConfigurations
73
91
74
92
Some tables may have _many_ columns available. In these situations, it is not useful for a user to be shown every single column at once. A `TableConfiguration` describes groupings of columns that should be used together, along with metadata information such as `ColumnRoles`. Every `Table` must provide at least one `TableConfiguration`.
75
93
@@ -86,10 +104,12 @@ var tableConfig = new TableConfiguration("All Data")
86
104
};
87
105
```
88
106
89
-
You also specify [Special Columns](../Glossary.md##special-columns) in a `TableConfiguration`.
107
+
You also specify [Special Columns](../Glossary.md#special-columns) in a `TableConfiguration`.
90
108
91
109
Once a `TableConfiguration` is created, it is added to the table we're building by calling `ITableBuilder.AddTableConfiguration`:
92
110
111
+
> ⚠️ Note: `AddTableConfiguration` must be called on `ITableBuilder`, *not* on `ITableBuilderWithRowCount`.
112
+
93
113
```cs
94
114
tableBuilder.AddTableConfiguration(tableConfig);
95
115
```
@@ -99,7 +119,6 @@ It is also recommended to set a default `TableConfiguration`:
A `ColumnRole` is metadata information about a column that defines the column's role in data presentation. For example, a column of `Timestamp` values relative to the start of a `DataSource` may be marked as a "start time" Column:
There are many other things you can do with your `Tables`, such as adding `TableCommands` or configuring its default layout style. For more information, refer to the [Advanced Topics](./Advanced/Overview.md).
131
+
There are many other things you can do with your `Tables`, such as adding `TableCommands` or configuring its default layout style. For more information, refer to the [Advanced Topics](./Advanced/README.md).
Copy file name to clipboardExpand all lines: documentation/Using-the-SDK/Creating-a-simple-sdk-plugin.md
+3-4Lines changed: 3 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -57,14 +57,13 @@ There are 4 distinct steps in creating a Simple SDK Plugin:
57
57
This example assumes that we're using our `SimpleCustomDataProcessor` with the `ProcessingSource` created in [Creating an SDK Plugin](./Creating-your-plugin.md) that advertises support for `.txt` files beginning with `mydata`. Because of this, we are passing in the `filePaths` for all of the `mydata*.txt` files opened by the user.
58
58
59
59
60
-
3. Implement `ProcessAsyncCore`. This method will be called to process data sources passed into your `CustomDataProcessor`. Typically the data in the data source is parsed and converted from some raw form into something more
61
-
relevant and easily accessible to the processor.
60
+
3. Implement `ProcessAsyncCore`. This method will be called to process data sources passed into your `CustomDataProcessor`. Typically the data in the data source is parsed and converted from some raw form into something more relevant and easily accessible to the processor.
62
61
63
-
In this example, we're calling a `ParseFiles` method that converts lines in each file opened to ficticious`LineItem` objects. In a
62
+
In this example, we're calling a `ParseFiles` method that converts lines in each file opened to fictitious`LineItem` objects. In a
64
63
more realistic case, processing would probably be broken down into smaller units. For example, there might be logic
65
64
for parsing operating system processes and making that data queryable by time and or memory layout.
66
65
67
-
This method is also typically where `this.dataSourceInfo`would be set (see below).
66
+
This method is usually where `this.dataSourceInfo`is set (see below).
0 commit comments