Skip to content

Commit 37304a9

Browse files
MSDN-WhiteKnightMSDN-WhiteKnight
authored
Add documentation for SequencePoint (#7582)
1 parent 781ebb1 commit 37304a9

File tree

4 files changed

+129
-24
lines changed

4 files changed

+129
-24
lines changed

‎samples/snippets/csharp/System.Reflection.Metadata/SequencePoint/Overview/Program.cs‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
using System;
2+
using System.IO;
3+
using System.Reflection;
4+
5+
namespace SequencePointSnippets
6+
{
7+
class Program
8+
{
9+
static void Main(string[] args)
10+
{
11+
string pdbPath = Path.Combine(Path.GetDirectoryName(typeof(Program).Assembly.Location), "SequencePointSnippets.pdb");
12+
SequencePointSnippets.ReadSourceLineData(pdbPath, MethodInfo.GetCurrentMethod().MetadataToken);
13+
}
14+
}
15+
}

‎samples/snippets/csharp/System.Reflection.Metadata/SequencePoint/Overview/SequencePointSnippets.cs‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
using System;
2+
using System.IO;
3+
using System.Reflection.Metadata;
4+
using System.Reflection.Metadata.Ecma335;
5+
6+
namespace SequencePointSnippets
7+
{
8+
static class SequencePointSnippets
9+
{
10+
//<SnippetReadSourceLineData>
11+
public static void ReadSourceLineData(string pdbPath, int methodToken)
12+
{
13+
// Determine method row number
14+
EntityHandle ehMethod = MetadataTokens.EntityHandle(methodToken);
15+
16+
if (ehMethod.Kind != HandleKind.MethodDefinition)
17+
{
18+
Console.WriteLine($"Invalid token kind: {ehMethod.Kind}");
19+
return;
20+
}
21+
22+
int rowNumber = MetadataTokens.GetRowNumber(ehMethod);
23+
24+
// MethodDebugInformation table is indexed by same row numbers as MethodDefinition table
25+
MethodDebugInformationHandle hDebug = MetadataTokens.MethodDebugInformationHandle(rowNumber);
26+
27+
// Open Portable PDB file
28+
using var fs = new FileStream(pdbPath, FileMode.Open, FileAccess.Read, FileShare.ReadWrite);
29+
using MetadataReaderProvider provider = MetadataReaderProvider.FromPortablePdbStream(fs);
30+
MetadataReader reader = provider.GetMetadataReader();
31+
32+
if (rowNumber > reader.MethodDebugInformation.Count)
33+
{
34+
Console.WriteLine("Error: Method row number is out of range");
35+
return;
36+
}
37+
38+
// Print source line information as console table
39+
MethodDebugInformation di = reader.GetMethodDebugInformation(hDebug);
40+
Console.WriteLine("IL offset | Start line | Start col. | End line | End col. |");
41+
42+
foreach (SequencePoint sp in di.GetSequencePoints())
43+
{
44+
if (sp.IsHidden)
45+
{
46+
Console.WriteLine($"{sp.Offset.ToString().PadLeft(9)} | (hidden sequence point)");
47+
}
48+
else
49+
{
50+
Console.WriteLine("{0} |{1} |{2} |{3} |{4} |",
51+
sp.Offset.ToString().PadLeft(9),
52+
sp.StartLine.ToString().PadLeft(11),
53+
sp.StartColumn.ToString().PadLeft(11),
54+
sp.EndLine.ToString().PadLeft(9),
55+
sp.EndColumn.ToString().PadLeft(9));
56+
}
57+
}
58+
}
59+
//</SnippetReadSourceLineData>
60+
}
61+
}

‎samples/snippets/csharp/System.Reflection.Metadata/SequencePoint/Overview/SequencePointSnippets.csproj‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<OutputType>Exe</OutputType>
5+
<TargetFramework>net6.0</TargetFramework>
6+
</PropertyGroup>
7+
8+
</Project>

‎xml/System.Reflection.Metadata/SequencePoint.xml‎

Lines changed: 45 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,17 @@
3535
</Attribute>
3636
</Attributes>
3737
<Docs>
38-
<summary>To be added.</summary>
39-
<remarks>To be added.</remarks>
38+
<summary>Represents a Portable PDB sequence point.</summary>
39+
<remarks>
40+
<format type="text/markdown"><![CDATA[
41+
## Remarks
42+
Sequence point is a structure that contains the mapping between IL offset and corresponding line and column numbers in a source document this IL was compiled from. Sequence points are stored in the `MethodDebugInformation` table of Portable PDB debugging symbols. For more information, see [Portable PDB v1.0: Format Specification](https://github.com/dotnet/runtime/blob/main/docs/design/specs/PortablePdb-Metadata.md#methoddebuginformation-table-0x31).
43+
44+
## Examples
45+
This example shows how to read sequence points of the method defined by the metadata token and display its source line mappings:
46+
[!code-csharp[](~/samples/snippets/csharp/System.Reflection.Metadata/SequencePoint/Overview/SequencePointSnippets.cs#ReadSourceLineData)]
47+
]]></format>
48+
</remarks>
4049
</Docs>
4150
<Members>
4251
<Member MemberName="Document">
@@ -62,8 +71,8 @@
6271
<ReturnType>System.Reflection.Metadata.DocumentHandle</ReturnType>
6372
</ReturnValue>
6473
<Docs>
65-
<summary>To be added.</summary>
66-
<value>To be added.</value>
74+
<summary>Gets the source document that contains this sequence point.</summary>
75+
<value>The source document that contains this sequence point.</value>
6776
<remarks>To be added.</remarks>
6877
</Docs>
6978
</Member>
@@ -90,8 +99,8 @@
9099
<ReturnType>System.Int32</ReturnType>
91100
</ReturnValue>
92101
<Docs>
93-
<summary>To be added.</summary>
94-
<value>To be added.</value>
102+
<summary>Gets the column number of the last character in this sequence point.</summary>
103+
<value>The column number of the last character in this sequence point.</value>
95104
<remarks>To be added.</remarks>
96105
</Docs>
97106
</Member>
@@ -118,8 +127,8 @@
118127
<ReturnType>System.Int32</ReturnType>
119128
</ReturnValue>
120129
<Docs>
121-
<summary>To be added.</summary>
122-
<value>To be added.</value>
130+
<summary>Gets the line number of the last character in this sequence point.</summary>
131+
<value>The line number of the last character in this sequence point.</value>
123132
<remarks>To be added.</remarks>
124133
</Docs>
125134
</Member>
@@ -150,9 +159,9 @@
150159
<Parameter Name="obj" Type="System.Object" />
151160
</Parameters>
152161
<Docs>
153-
<param name="obj">To be added.</param>
154-
<summary>To be added.</summary>
155-
<returns>To be added.</returns>
162+
<param name="obj">The object to compare with the current object.</param>
163+
<summary>Indicates whether the current sequence point is equal to the specified object.</summary>
164+
<returns><see langword="true" /> if the current sequence point is equal to the <paramref name="obj" /> parameter; otherwise, <see langword="false" />.</returns>
156165
<remarks>To be added.</remarks>
157166
</Docs>
158167
</Member>
@@ -216,8 +225,8 @@
216225
</ReturnValue>
217226
<Parameters />
218227
<Docs>
219-
<summary>To be added.</summary>
220-
<returns>To be added.</returns>
228+
<summary>Gets the hash code of this sequence point.</summary>
229+
<returns>The hash code of this sequence point.</returns>
221230
<remarks>To be added.</remarks>
222231
</Docs>
223232
</Member>
@@ -245,8 +254,14 @@
245254
</ReturnValue>
246255
<MemberValue>16707566</MemberValue>
247256
<Docs>
248-
<summary>To be added.</summary>
249-
<remarks>To be added.</remarks>
257+
<summary>Specifies a line number value for a hidden sequence point.</summary>
258+
<remarks>
259+
<format type="text/markdown"><![CDATA[
260+
## Remarks
261+
Some sequence points represent a special IL synthesized by the compiler that does not map to any source document line. Such sequence points have a line number value equal to this constant (0xfeefee). For more information, see [Portable PDB v1.0: Format Specification](https://github.com/dotnet/runtime/blob/main/docs/design/specs/PortablePdb-Metadata.md#methoddebuginformation-table-0x31).
262+
263+
]]></format>
264+
</remarks>
250265
</Docs>
251266
</Member>
252267
<Member MemberName="IsHidden">
@@ -272,9 +287,15 @@
272287
<ReturnType>System.Boolean</ReturnType>
273288
</ReturnValue>
274289
<Docs>
275-
<summary>To be added.</summary>
276-
<value>To be added.</value>
277-
<remarks>To be added.</remarks>
290+
<summary>Gets a value that indicates whether this sequence point is hidden.</summary>
291+
<value><see langword="true" /> if this sequence point is hidden; otherwise, <see langword="false" />.</value>
292+
<remarks>
293+
<format type="text/markdown"><![CDATA[
294+
## Remarks
295+
A hidden sequence point is a sequence point that represents a special IL synthesized by the compiler that does not map to any source document line. For more information, see [Portable PDB v1.0: Format Specification](https://github.com/dotnet/runtime/blob/main/docs/design/specs/PortablePdb-Metadata.md#methoddebuginformation-table-0x31).
296+
297+
]]></format>
298+
</remarks>
278299
</Docs>
279300
</Member>
280301
<Member MemberName="Offset">
@@ -300,8 +321,8 @@
300321
<ReturnType>System.Int32</ReturnType>
301322
</ReturnValue>
302323
<Docs>
303-
<summary>To be added.</summary>
304-
<value>To be added.</value>
324+
<summary>Gets the IL offset of this sequence point from the start of the method body, in bytes.</summary>
325+
<value>The IL offset of this sequence point from the start of the method body, in bytes.</value>
305326
<remarks>To be added.</remarks>
306327
</Docs>
307328
</Member>
@@ -328,8 +349,8 @@
328349
<ReturnType>System.Int32</ReturnType>
329350
</ReturnValue>
330351
<Docs>
331-
<summary>To be added.</summary>
332-
<value>To be added.</value>
352+
<summary>Gets the column number of the first character in this sequence point.</summary>
353+
<value>The column number of the first character in this sequence point.</value>
333354
<remarks>To be added.</remarks>
334355
</Docs>
335356
</Member>
@@ -356,8 +377,8 @@
356377
<ReturnType>System.Int32</ReturnType>
357378
</ReturnValue>
358379
<Docs>
359-
<summary>To be added.</summary>
360-
<value>To be added.</value>
380+
<summary>Gets the line number of the first character in this sequence point.</summary>
381+
<value>The line number of the first character in this sequence point.</value>
361382
<remarks>To be added.</remarks>
362383
</Docs>
363384
</Member>

0 commit comments

Comments
 (0)