Skip to content

Commit 601c540

Browse files
tarekghtarekgh
authored
Merge pull request #10859 from dotnet/MiscNotesForLCIDandMetricCounters
Misc notes for LCID deprecation and Metric observable counters report…
2 parents 1935e02 + 25be289 commit 601c540

File tree

4 files changed

+129
-9
lines changed

4 files changed

+129
-9
lines changed

‎xml/System.Diagnostics.Metrics/Meter.xml

Lines changed: 91 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -765,6 +765,9 @@ Example uses for Histogram: The request duration and the size of the response pa
765765
766766
## Remarks
767767
768+
> [!NOTE]
769+
> Unlike `Counter`, which takes the increment/delta value, the callback function reports the absolute value of the counter. To determine the reported rate the counter is changing, the difference between successive measurements is used.
770+
768771
Example uses for ObservableCounter: The number of page faults for each process.
769772
770773
]]></format>
@@ -836,6 +839,9 @@ Example uses for ObservableCounter: The number of page faults for each process.
836839
837840
## Remarks
838841
842+
> [!NOTE]
843+
> Unlike Counter which takes the increment/delta value, the callback function reports the absolute value of the counter. To determine the reported rate the counter is changing, the difference between successive measurements is used.
844+
839845
Example uses for ObservableCounter: The number of page faults for each process.
840846
841847
]]></format>
@@ -907,6 +913,9 @@ Example uses for ObservableCounter: The number of page faults for each process.
907913
908914
## Remarks
909915
916+
> [!NOTE]
917+
> Unlike Counter which takes the increment/delta value, the callback function reports the absolute value of the counter. To determine the reported rate the counter is changing, the difference between successive measurements is used.
918+
910919
Example uses for ObservableCounter: The number of page faults for each process.
911920
912921
]]></format>
@@ -992,7 +1001,18 @@ Example uses for ObservableCounter: The number of page faults for each process.
9921001
<param name="tags">The tags to attach to the counter.</param>
9931002
<summary>Creates an ObservableCounter instance, which is an Instrument that reports monotonically increasing value(s) when the instrument is being observed.</summary>
9941003
<returns>A new observable counter.</returns>
995-
<remarks>Example uses for ObservableCounter: The number of page faults for each process.</remarks>
1004+
<remarks>
1005+
<format type="text/markdown"><![CDATA[
1006+
1007+
## Remarks
1008+
1009+
> [!NOTE]
1010+
> Unlike `Counter`, which takes the increment/delta value, the callback function reports the absolute value of the counter. To determine the reported rate the counter is changing, the difference between successive measurements is used.
1011+
1012+
Example uses for `ObservableCounter`: The number of page faults for each process.
1013+
1014+
]]></format>
1015+
</remarks>
9961016
</Docs>
9971017
</Member>
9981018
<Member MemberName="CreateObservableCounter&lt;T&gt;">
@@ -1074,7 +1094,17 @@ Example uses for ObservableCounter: The number of page faults for each process.
10741094
<param name="tags">The tags to attach to the counter.</param>
10751095
<summary>Creates an ObservableCounter instance, which is an Instrument that reports monotonically increasing value(s) when the instrument is being observed.</summary>
10761096
<returns>A new observable counter.</returns>
1077-
<remarks>Example uses for ObservableCounter: The number of page faults for each process.</remarks>
1097+
<remarks>
1098+
<format type="text/markdown"><![CDATA[
1099+
## Remarks
1100+
1101+
> [!NOTE]
1102+
> Unlike Counter which takes the increment/delta value, the callback function reports the absolute value of the counter. To determine the reported rate the counter is changing, the difference between successive measurements is used.
1103+
1104+
Example uses for ObservableCounter: The number of page faults for each process.
1105+
1106+
]]></format>
1107+
</remarks>
10781108
</Docs>
10791109
</Member>
10801110
<Member MemberName="CreateObservableCounter&lt;T&gt;">
@@ -1156,7 +1186,18 @@ Example uses for ObservableCounter: The number of page faults for each process.
11561186
<param name="tags">The tags to attach to the counter.</param>
11571187
<summary>Creates an ObservableCounter instance, which is an Instrument that reports monotonically increasing value(s) when the instrument is being observed.</summary>
11581188
<returns>A new observable counter.</returns>
1159-
<remarks>Example uses for ObservableCounter: The number of page faults for each process.</remarks>
1189+
<remarks>
1190+
<format type="text/markdown"><![CDATA[
1191+
1192+
## Remarks
1193+
1194+
> [!NOTE]
1195+
> Unlike Counter which takes the increment/delta value, the callback function reports the absolute value of the counter. To determine the reported rate the counter is changing, the difference between successive measurements is used.
1196+
1197+
Example uses for ObservableCounter: The number of page faults for each process.
1198+
1199+
]]></format>
1200+
</remarks>
11601201
</Docs>
11611202
</Member>
11621203
<Member MemberName="CreateObservableGauge&lt;T&gt;">
@@ -1658,6 +1699,9 @@ Example uses for ObservableCounter: The number of page faults for each process.
16581699
16591700
## Remarks
16601701
1702+
> [!NOTE]
1703+
> Unlike UpDownCounter which takes the increment/delta value, the callback function reports the absolute value of the ObservableUpDownCounter. To determine the reported rate the ObservableUpDownCounter is changing, the difference between successive measurements is used.
1704+
16611705
Example uses for ObservableUpDownCounter: the process heap size or the approximate number of items in a lock-free circular buffer.
16621706
16631707
]]></format>
@@ -1728,6 +1772,9 @@ Example uses for ObservableUpDownCounter: the process heap size or the approxima
17281772
17291773
## Remarks
17301774
1775+
> [!NOTE]
1776+
> Unlike UpDownCounter which takes the increment/delta value, the callback function reports the absolute value of the ObservableUpDownCounter. To determine the reported rate the ObservableUpDownCounter is changing, the difference between successive measurements is used.
1777+
17311778
Example uses for ObservableUpDownCounter: the process heap size or the approximate number of items in a lock-free circular buffer.
17321779
17331780
]]></format>
@@ -1798,6 +1845,9 @@ Example uses for ObservableUpDownCounter: the process heap size or the approxima
17981845
17991846
## Remarks
18001847
1848+
> [!NOTE]
1849+
> Unlike UpDownCounter which takes the increment/delta value, the callback function reports the absolute value of the ObservableUpDownCounter. To determine the reported rate the ObservableUpDownCounter is changing, the difference between successive measurements is used.
1850+
18011851
Example uses for ObservableUpDownCounter: the process heap size or the approximate number of items in a lock-free circular buffer.
18021852
18031853
]]></format>
@@ -1883,7 +1933,19 @@ Example uses for ObservableUpDownCounter: the process heap size or the approxima
18831933
<param name="tags">tags to attach to the counter.</param>
18841934
<summary>Create an ObservableUpDownCounter object. ObservableUpDownCounter is an Instrument which reports increasing or decreasing value(s) when the instrument is being observed.</summary>
18851935
<returns>A new observable up down counter.</returns>
1886-
<remarks>Example uses for ObservableUpDownCounter: the process heap size or the approximate number of items in a lock-free circular buffer.</remarks>
1936+
<remarks>
1937+
<format type="text/markdown"><![CDATA[
1938+
1939+
## Remarks
1940+
1941+
> [!NOTE]
1942+
> Unlike `UpDownCounter`, which takes the increment/delta value, the callback function reports the absolute value of the `ObservableUpDownCounter`. To determine the reported rate the `ObservableUpDownCounter` is changing, the difference between successive measurements is used.
1943+
1944+
Example uses for `ObservableUpDownCounter`: the process heap size or the approximate number of items in a lock-free circular buffer.
1945+
1946+
]]></format>
1947+
</remarks>
1948+
18871949
</Docs>
18881950
</Member>
18891951
<Member MemberName="CreateObservableUpDownCounter&lt;T&gt;">
@@ -1965,7 +2027,19 @@ Example uses for ObservableUpDownCounter: the process heap size or the approxima
19652027
<param name="tags">tags to attach to the counter.</param>
19662028
<summary>Create an ObservableUpDownCounter object. ObservableUpDownCounter is an Instrument which reports increasing or decreasing value(s) when the instrument is being observed.</summary>
19672029
<returns>A new observable up down counter.</returns>
1968-
<remarks>Example uses for ObservableUpDownCounter: the process heap size or the approximate number of items in a lock-free circular buffer.</remarks>
2030+
<remarks>
2031+
<format type="text/markdown"><![CDATA[
2032+
2033+
## Remarks
2034+
2035+
> [!NOTE]
2036+
> Unlike UpDownCounter which takes the increment/delta value, the callback function reports the absolute value of the ObservableUpDownCounter. To determine the reported rate the ObservableUpDownCounter is changing, the difference between successive measurements is used.
2037+
2038+
Example uses for ObservableUpDownCounter: the process heap size or the approximate number of items in a lock-free circular buffer.
2039+
2040+
]]></format>
2041+
</remarks>
2042+
19692043
</Docs>
19702044
</Member>
19712045
<Member MemberName="CreateObservableUpDownCounter&lt;T&gt;">
@@ -2047,7 +2121,18 @@ Example uses for ObservableUpDownCounter: the process heap size or the approxima
20472121
<param name="tags">tags to attach to the counter.</param>
20482122
<summary>Create an ObservableUpDownCounter object. ObservableUpDownCounter is an Instrument which reports increasing or decreasing value(s) when the instrument is being observed.</summary>
20492123
<returns>A new observable up down counter.</returns>
2050-
<remarks>Example uses for ObservableUpDownCounter: the process heap size or the approximate number of items in a lock-free circular buffer.</remarks>
2124+
<remarks>
2125+
<format type="text/markdown"><![CDATA[
2126+
2127+
## Remarks
2128+
2129+
> [!NOTE]
2130+
> Unlike UpDownCounter which takes the increment/delta value, the callback function reports the absolute value of the ObservableUpDownCounter. To determine the reported rate the ObservableUpDownCounter is changing, the difference between successive measurements is used.
2131+
2132+
Example uses for ObservableUpDownCounter: the process heap size or the approximate number of items in a lock-free circular buffer.
2133+
2134+
]]></format>
2135+
</remarks>
20512136
</Docs>
20522137
</Member>
20532138
<Member MemberName="CreateUpDownCounter&lt;T&gt;">

‎xml/System.Diagnostics.Metrics/ObservableCounter`1.xml

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,9 @@
3636
3737
## Remarks
3838
39+
> [!NOTE]
40+
> Unlike `Counter`, which takes the increment/delta value, the callback function reports the absolute value of the counter. To determine the reported rate the counter is changing, the difference between successive measurements is used.
41+
3942
This class supports only the following generic parameter types: <xref:System.Byte>, <xref:System.Int16>, <xref:System.Int32>, <xref:System.Int64>, <xref:System.Single>, <xref:System.Double>, and <xref:System.Decimal>.
4043
4144
]]></format>
@@ -65,7 +68,16 @@ This class supports only the following generic parameter types: <xref:System.Byt
6568
<Docs>
6669
<summary>Fetches the current measurements being tracked by this observable counter.</summary>
6770
<returns>The current measurements being tracked by this observable counter.</returns>
68-
<remarks>To be added.</remarks>
71+
<remarks>
72+
<format type="text/markdown"><![CDATA[
73+
74+
## Remarks
75+
76+
> [!NOTE]
77+
> Unlike Counter which takes the increment/delta value, the callback function reports the absolute value of the counter. To determine the reported rate the counter is changing, the difference between successive measurements is used.
78+
79+
]]></format>
80+
</remarks>
6981
</Docs>
7082
</Member>
7183
</Members>

‎xml/System.Diagnostics.Metrics/ObservableUpDownCounter`1.xml

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,9 @@ To create an ObservableUpDownCounter object, use the <see cref="Overload:System.
3737
3838
## Remarks
3939
40+
> [!NOTE]
41+
> Unlike `UpDownCounter`, which takes the increment/delta value, the callback function reports the absolute value of the `ObservableUpDownCounter`. To determine the reported rate that the `ObservableUpDownCounter` is changing, the difference between successive measurements is used.
42+
4043
This class supports only the following generic parameter types: <xref:System.Byte>, <xref:System.Int16>, <xref:System.Int32>, <xref:System.Int64>, <xref:System.Single>, <xref:System.Double>, and <xref:System.Decimal>.
4144
4245
]]></format>
@@ -64,7 +67,17 @@ This class supports only the following generic parameter types: <xref:System.Byt
6467
<Docs>
6568
<summary>Fetches the current measurements being tracked by this observable counter.</summary>
6669
<returns>To be added.</returns>
67-
<remarks>To be added.</remarks>
70+
<remarks>
71+
<format type="text/markdown"><![CDATA[
72+
73+
## Remarks
74+
75+
> [!NOTE]
76+
> Unlike UpDownCounter which takes the increment/delta value, the callback function reports the absolute value of the ObservableUpDownCounter. To determine the reported rate the ObservableUpDownCounter is changing, the difference between successive measurements is used.
77+
78+
]]></format>
79+
</remarks>
80+
6881
</Docs>
6982
</Member>
7083
</Members>

‎xml/System.Globalization/CultureInfo.xml

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,9 @@ Predefined culture identifiers for cultures available on Windows system are list
173173
> [!NOTE]
174174
> For backwards compatibility, a culture constructed using a `culture` parameter of 0x0004 or 0x7c04 will have a <xref:System.Globalization.CultureInfo.Name%2A> property of `zh-CHS` or `zh-CHT`, respectively. You should instead prefer to construct the culture using the current standard culture names of `zh-Hans` or `zh-Hant`, unless you have a reason for using the older names.
175175
176+
> [!NOTE]
177+
> LCIDs are being deprecated, and implementers are strongly encouraged to use newer versions of APIs that support BCP 47 locale names instead. Each LCID can be represented by a BCP 47 locale name, but the reverse is not true. The LCID range is restricted and unable to uniquely identify all the possible combinations of language and region.
178+
176179
]]></format>
177180
</remarks>
178181
<exception cref="T:System.ArgumentOutOfRangeException">
@@ -361,6 +364,9 @@ Predefined culture identifiers available on Windows systems are listed in the **
361364
> [!NOTE]
362365
> For backwards compatibility, a culture constructed using a `culture` parameter of 0x0004 or 0x7c04 will have a <xref:System.Globalization.CultureInfo.Name%2A> property of zh-CHS or zh-CHT, respectively. You should instead prefer to construct the culture using the current standard culture names of `zh-Hans` or zh-Hant, unless you have a reason for using the older names.
363366
367+
> [!NOTE]
368+
> LCIDs are being deprecated, and implementers are strongly encouraged to use newer versions of APIs that support BCP 47 locale names instead. Each LCID can be represented by a BCP 47 locale name, but the reverse is not true. The LCID range is restricted and unable to uniquely identify all the possible combinations of language and region.
369+
364370
]]></format>
365371
</remarks>
366372
<exception cref="T:System.ArgumentOutOfRangeException">
@@ -1775,6 +1781,9 @@ csc /resource:GreetingStrings.resources Example1.cs
17751781
17761782
If `culture` is the locale identifier of the current culture, the returned <xref:System.Globalization.CultureInfo> object does not reflect any user overrides.
17771783
1784+
> [!NOTE]
1785+
> LCIDs are being deprecated, and implementers are strongly encouraged to use newer versions of APIs that support BCP 47 locale names instead. Each LCID can be represented by a BCP 47 locale name, but the reverse is not true. The LCID range is restricted and unable to uniquely identify all the possible combinations of language and region.
1786+
17781787
]]></format>
17791788
</remarks>
17801789
<exception cref="T:System.ArgumentOutOfRangeException">
@@ -2690,7 +2699,8 @@ Setting `predefinedOnly` to `true` will ensure a culture is created only if the
26902699
26912700
In versions of Windows prior to Windows 10, the locale identifier `LOCALE_CUSTOM_UNSPECIFIED` (0x1000, or 4096) is assigned to custom cultures created by the user. Starting with Windows 10, it is assigned to any culture that does not have a unique locale identifier and does not have complete system-provided data. As a result, code that iterates cultures and retrieves those with an <xref:System.Globalization.CultureInfo.LCID%2A> value of `LOCALE_CUSTOM_UNSPECIFIED` returns a larger subset of <xref:System.Globalization.CultureInfo> objects if run under Windows 10.
26922701
2693-
2702+
> [!NOTE]
2703+
> LCIDs are being deprecated, and implementers are strongly encouraged to use newer versions of APIs that support BCP 47 locale names instead. Each LCID can be represented by a BCP 47 locale name, but the reverse is not true. The LCID range is restricted and unable to uniquely identify all the possible combinations of language and region.
26942704
26952705
## Examples
26962706
The following code example shows how to create a <xref:System.Globalization.CultureInfo> for Spanish (Spain) with the international sort order and another <xref:System.Globalization.CultureInfo> with the traditional sort order.

0 commit comments

Comments
 (0)