Merge main into live

.github/policies/mention-owners.yml

@@ -406,6 +406,26 @@ configuration:
                   replyTemplate: >-
                     Tagging subscribers to this area: ${mentionees}
                   assignMentionees: False
+          - if:
+              - labelAdded:
+                  label: area-Extensions-AI
+            then:
+              - mentionUsers:
+                  mentionees:
+                    - dotnet/dotnet-extensions-ai
+                  replyTemplate: >-
+                    Tagging subscribers to this area: ${mentionees}
+                  assignMentionees: False
+          - if:
+              - labelAdded:
+                  label: area-Extensions-AI-Evaluation
+            then:
+              - mentionUsers:
+                  mentionees:
+                    - dotnet/dotnet-extensions-ai-evaluation
+                  replyTemplate: >-
+                    Tagging subscribers to this area: ${mentionees}
+                  assignMentionees: False
           - if:
               - labelAdded:
                   label: area-Extensions-Caching

snippets/csharp/System.IO/Path/ChangeExtension/pathmembers.cs

@@ -61,31 +61,30 @@ public void Combine()
     public void GetDirectoryName()
     {
         // <Snippet3>
-        string filePath = @"C:\MyDir\MySubDir\myfile.ext";
-        string directoryName;
-        int i = 0;
-
-        while (filePath != null)
-        {
-            directoryName = Path.GetDirectoryName(filePath);
-            Console.WriteLine("GetDirectoryName('{0}') returns '{1}'",
-                filePath, directoryName);
-            filePath = directoryName;
-            if (i == 1)
-            {
-                filePath = directoryName + @"\";  // this will preserve the previous path
-            }
-            i++;
-        }
-        /*
-        This code produces the following output:
-
-        GetDirectoryName('C:\MyDir\MySubDir\myfile.ext') returns 'C:\MyDir\MySubDir'
-        GetDirectoryName('C:\MyDir\MySubDir') returns 'C:\MyDir'
-        GetDirectoryName('C:\MyDir\') returns 'C:\MyDir'
-        GetDirectoryName('C:\MyDir') returns 'C:\'
-        GetDirectoryName('C:\') returns ''
-        */
+    string? filePath = @"C:\MyDir\MySubDir\myfile.ext";
+    string? directoryName;
+    int i = 0;
+
+    while (filePath != null)
+    {
+        directoryName = Path.GetDirectoryName(filePath);
+        Console.WriteLine($"GetDirectoryName(\"{filePath}\") returns {directoryName ?? "NULL"}");
+
+        filePath = (i == 1)
+            ? directoryName + @"\"  // this will preserve the previous path
+            : directoryName;
+
+        i++;
+    }
+    /*
+    This code produces the following output:
+
+    GetDirectoryName("C:\MyDir\MySubDir\myfile.ext") returns C:\MyDir\MySubDir
+    GetDirectoryName("C:\MyDir\MySubDir") returns C:\MyDir
+    GetDirectoryName("C:\MyDir\") returns C:\MyDir
+    GetDirectoryName("C:\MyDir") returns C:\
+    GetDirectoryName("C:\") returns NULL
+    */
         // </Snippet3>
 
         Console.WriteLine();
@@ -378,4 +377,4 @@ public static void Main()
         pathSnippets.HasExtension();
         pathSnippets.IsPathRooted();
     }
-}
+}

xml/System.Diagnostics.Metrics/Meter.xml

@@ -765,6 +765,9 @@ Example uses for Histogram: The request duration and the size of the response pa
 
 ## Remarks
 
+> [!NOTE]
+> 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.
+
 Example uses for ObservableCounter: The number of page faults for each process.
 
           ]]></format>
@@ -836,6 +839,9 @@ Example uses for ObservableCounter: The number of page faults for each process.
 
 ## Remarks
 
+> [!NOTE]
+> 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.
+
 Example uses for ObservableCounter: The number of page faults for each process.
 
           ]]></format>
@@ -907,6 +913,9 @@ Example uses for ObservableCounter: The number of page faults for each process.
 
 ## Remarks
 
+> [!NOTE]
+> 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.
+
 Example uses for ObservableCounter: The number of page faults for each process.
 
           ]]></format>
@@ -992,7 +1001,18 @@ Example uses for ObservableCounter: The number of page faults for each process.
         <param name="tags">The tags to attach to the counter.</param>
         <summary>Creates an ObservableCounter instance, which is an Instrument that reports monotonically increasing value(s) when the instrument is being observed.</summary>
         <returns>A new observable counter.</returns>
-        <remarks>Example uses for ObservableCounter: The number of page faults for each process.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+> [!NOTE]
+> 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.
+
+Example uses for `ObservableCounter`: The number of page faults for each process.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="CreateObservableCounter&lt;T&gt;">
@@ -1074,7 +1094,17 @@ Example uses for ObservableCounter: The number of page faults for each process.
         <param name="tags">The tags to attach to the counter.</param>
         <summary>Creates an ObservableCounter instance, which is an Instrument that reports monotonically increasing value(s) when the instrument is being observed.</summary>
         <returns>A new observable counter.</returns>
-        <remarks>Example uses for ObservableCounter: The number of page faults for each process.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+## Remarks
+
+> [!NOTE]
+> 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.
+
+Example uses for ObservableCounter: The number of page faults for each process.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="CreateObservableCounter&lt;T&gt;">
@@ -1156,7 +1186,18 @@ Example uses for ObservableCounter: The number of page faults for each process.
         <param name="tags">The tags to attach to the counter.</param>
         <summary>Creates an ObservableCounter instance, which is an Instrument that reports monotonically increasing value(s) when the instrument is being observed.</summary>
         <returns>A new observable counter.</returns>
-        <remarks>Example uses for ObservableCounter: The number of page faults for each process.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+> [!NOTE]
+> 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.
+
+Example uses for ObservableCounter: The number of page faults for each process.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="CreateObservableGauge&lt;T&gt;">
@@ -1658,6 +1699,9 @@ Example uses for ObservableCounter: The number of page faults for each process.
 
 ## Remarks
 
+> [!NOTE]
+> 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.
+
 Example uses for ObservableUpDownCounter: the process heap size or the approximate number of items in a lock-free circular buffer.
 
           ]]></format>
@@ -1728,6 +1772,9 @@ Example uses for ObservableUpDownCounter: the process heap size or the approxima
 
 ## Remarks
 
+> [!NOTE]
+> 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.
+
 Example uses for ObservableUpDownCounter: the process heap size or the approximate number of items in a lock-free circular buffer.
 
           ]]></format>
@@ -1798,6 +1845,9 @@ Example uses for ObservableUpDownCounter: the process heap size or the approxima
 
 ## Remarks
 
+> [!NOTE]
+> 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.
+
 Example uses for ObservableUpDownCounter: the process heap size or the approximate number of items in a lock-free circular buffer.
 
           ]]></format>
@@ -1883,7 +1933,19 @@ Example uses for ObservableUpDownCounter: the process heap size or the approxima
         <param name="tags">tags to attach to the counter.</param>
         <summary>Create an ObservableUpDownCounter object. ObservableUpDownCounter is an Instrument which reports increasing or decreasing value(s) when the instrument is being observed.</summary>
         <returns>A new observable up down counter.</returns>
-        <remarks>Example uses for ObservableUpDownCounter: the process heap size or the approximate number of items in a lock-free circular buffer.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+> [!NOTE]
+> 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.
+
+Example uses for `ObservableUpDownCounter`: the process heap size or the approximate number of items in a lock-free circular buffer.
+
+          ]]></format>
+        </remarks>
+
       </Docs>
     </Member>
     <Member MemberName="CreateObservableUpDownCounter&lt;T&gt;">
@@ -1965,7 +2027,19 @@ Example uses for ObservableUpDownCounter: the process heap size or the approxima
         <param name="tags">tags to attach to the counter.</param>
         <summary>Create an ObservableUpDownCounter object. ObservableUpDownCounter is an Instrument which reports increasing or decreasing value(s) when the instrument is being observed.</summary>
         <returns>A new observable up down counter.</returns>
-        <remarks>Example uses for ObservableUpDownCounter: the process heap size or the approximate number of items in a lock-free circular buffer.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+> [!NOTE]
+> 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.
+
+Example uses for ObservableUpDownCounter: the process heap size or the approximate number of items in a lock-free circular buffer.
+
+          ]]></format>
+        </remarks>
+
       </Docs>
     </Member>
     <Member MemberName="CreateObservableUpDownCounter&lt;T&gt;">
@@ -2047,7 +2121,18 @@ Example uses for ObservableUpDownCounter: the process heap size or the approxima
         <param name="tags">tags to attach to the counter.</param>
         <summary>Create an ObservableUpDownCounter object. ObservableUpDownCounter is an Instrument which reports increasing or decreasing value(s) when the instrument is being observed.</summary>
         <returns>A new observable up down counter.</returns>
-        <remarks>Example uses for ObservableUpDownCounter: the process heap size or the approximate number of items in a lock-free circular buffer.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+> [!NOTE]
+> 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.
+
+Example uses for ObservableUpDownCounter: the process heap size or the approximate number of items in a lock-free circular buffer.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="CreateUpDownCounter&lt;T&gt;">

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

@@ -36,6 +36,9 @@
 
 ## Remarks
 
+> [!NOTE]
+> 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.
+
 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>.
 
       ]]></format>
@@ -65,7 +68,16 @@ This class supports only the following generic parameter types: <xref:System.Byt
       <Docs>
         <summary>Fetches the current measurements being tracked by this observable counter.</summary>
         <returns>The current measurements being tracked by this observable counter.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+> [!NOTE]
+> 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.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
   </Members>

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

@@ -37,6 +37,9 @@ To create an ObservableUpDownCounter object, use the <see cref="Overload:System.
 
 ## Remarks
 
+> [!NOTE]
+> 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.
+
 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>.
 
       ]]></format>
@@ -64,7 +67,17 @@ This class supports only the following generic parameter types: <xref:System.Byt
       <Docs>
         <summary>Fetches the current measurements being tracked by this observable counter.</summary>
         <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+> [!NOTE]
+> 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.
+
+          ]]></format>
+        </remarks>
+
       </Docs>
     </Member>
   </Members>

xml/System.Globalization/CultureInfo.xml

@@ -173,6 +173,9 @@ Predefined culture identifiers for cultures available on Windows system are list
 > [!NOTE]
 > 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.
 
+> [!NOTE]
+> 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.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentOutOfRangeException">
@@ -361,6 +364,9 @@ Predefined culture identifiers available on Windows systems are listed in the **
 > [!NOTE]
 > 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.
 
+> [!NOTE]
+> 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.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentOutOfRangeException">
@@ -1775,6 +1781,9 @@ csc /resource:GreetingStrings.resources Example1.cs
 
  If `culture` is the locale identifier of the current culture, the returned <xref:System.Globalization.CultureInfo> object does not reflect any user overrides.
 
+> [!NOTE]
+> 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.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentOutOfRangeException">
@@ -2690,7 +2699,8 @@ Setting `predefinedOnly` to `true` will ensure a culture is created only if the
 
  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.
 
-
+> [!NOTE]
+> 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.
 
 ## Examples
  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.