Merge pull request #19251 from nr-ahemsath/docs/net-agent-settransactionname-api-doc-improvements

docs: .NET Agent: Add clarifying examples to SetTransactionName API doc

Author: adutta-newrelic

src/content/docs/apm/agents/net-agent/net-agent-api/net-agent-api.mdx

@@ -2334,7 +2334,7 @@ The following list contains the different calls you can make with the API, inclu
 
     ### Description
 
-    Sets the name of the current transaction. Before you use this call, ensure you understand the implications of [metric grouping issues](/docs/agents/manage-apm-agents/troubleshooting/metric-grouping-issues).
+    Set a custom transaction name, to be appended after an initial prefix (`WebTransaction` or `OtherTransaction`) based on the type of the current transaction. Before you use this call, ensure you understand the implications of [metric grouping issues](/docs/agents/manage-apm-agents/troubleshooting/metric-grouping-issues).
 
     If you use this call multiple times within the same transaction, each call overwrites the previous call and the last call sets the name.
 
@@ -2392,8 +2392,71 @@ The following list contains the different calls you can make with the API, inclu
 
     ### Examples
 
+    This example shows use of this API in an ASP.NET Core MVC controller. A transaction is created automatically by the agent's instrumentation for ASP.NET Core. The first part of the transaction name will continue to be `WebTransaction`.
+
+    ```cs
+    public class HomeController : Controller
+    {
+
+      public IActionResult Order(string product)
+      { 
+
+        // The commented-out API call below is probably a bad idea and will lead to a metric grouping issue (MGI)
+        // because too many transaction names will be created. Don't do this.
+        //NewRelic.Api.Agent.NewRelic.SetTransactionName("Other", $"ProductOrder-{product}");
+
+        // Do this instead if you want to record request-specific data about this MVC endpoint
+        var tx = NewRelic.Api.Agent.NewRelic.GetAgent().CurrentTransaction;
+        tx.AddCustomAttribute("productName", product);
+
+        // The default transaction name at this point will be: WebTransaction/MVC/Home/Order
+
+        // Set custom transaction name
+        NewRelic.Api.Agent.NewRelic.SetTransactionName("Other", "OrderProduct");
+
+        // Transaction name is now: WebTransaction/Other/OrderProduct
+
+        return View();
+      }
+    }  
+    ```
+
+    This example shows use of this API in a console application. Note the `[Transaction]` custom instrumentation attribute, which is necessary to create a transaction for the example method.  The first part of the transaction name will continue to be `OtherTransaction`.
+
     ```cs
-    NewRelic.Api.Agent.NewRelic.SetTransactionName("Other", "MyTransaction");
+    using NewRelic.Api.Agent;
+
+    namespace SetApplicationNameConsoleExample
+    {
+      internal class Program
+      {
+        static void Main(string[] args)
+        {
+          Console.WriteLine("Hello, World!");
+
+            var start = DateTime.Now;
+            while (DateTime.Now - start < TimeSpan.FromMinutes(2))
+            {
+                DoSomething();
+                Thread.Sleep(TimeSpan.FromSeconds(5));
+            }
+        }
+
+        [Transaction]  // Attribute-based custom instrumentation to create a transaction for this method
+        static void DoSomething()
+        {
+            Console.WriteLine("Doing something: " + Guid.NewGuid().ToString());
+
+            // Transaction name from default naming at this point is: OtherTransaction/Custom/SetApplicationNameConsoleExample.Program/DoSomething
+
+            NewRelic.Api.Agent.NewRelic.SetTransactionName("Console", "MyCustomTransactionName");
+
+            // Transaction name at this point is: OtherTransaction/Console/MyCustomTransactionName
+
+            // Note, however, that this transaction will still have a child segment (span) named "SetApplicationNameConsoleExample.Program.DoSomething"
+        }
+      }
+    }
     ```
   </Collapser>
 
@@ -2420,7 +2483,7 @@ The following list contains the different calls you can make with the API, inclu
 
     ### Description
 
-    Sets the URI of the current transaction. The URI appears in the `request.uri` attribute of [transaction traces](/docs/apm/transactions/transaction-traces/transaction-traces) and [transaction events](/docs/using-new-relic/metrics/analyze-your-metrics/data-collection-metric-timeslice-event-data), and it also can affect transaction naming.
+    Set the URI of the current transaction. The URI appears in the `request.uri` attribute of [transaction traces](/docs/apm/transactions/transaction-traces/transaction-traces) and [transaction events](/docs/using-new-relic/metrics/analyze-your-metrics/data-collection-metric-timeslice-event-data), and it also can affect transaction naming.
 
     If you use this call multiple times within the same transaction, each call overwrites the previous call. The last call sets the URI.