done doc for newkustoclientrequestprops

Author: santisq

.vscode/settings.json

@@ -33,6 +33,7 @@
         "Entra",
         "Kusto",
         "multijson",
+        "norequesttimeout",
         "proga",
         "scsv",
         "singlejson",

docs/en-US/Invoke-KustoQuery.md

@@ -157,3 +157,5 @@ By default, this cmdlet outputs `PSObject`.
 [Kusto Query Language (KQL)](https://learn.microsoft.com/en-us/kusto/query/?view=microsoft-fabric)
 
 [T-SQL](https://learn.microsoft.com/en-us/kusto/query/t-sql?view=microsoft-fabric)
+
+[Send T-SQL queries via the REST API](https://learn.microsoft.com/en-us/kusto/api/rest/t-sql?view=microsoft-fabric)

docs/en-US/New-KustoClientRequestProperties.md

@@ -9,7 +9,7 @@ schema: 2.0.0
 
 ## SYNOPSIS
 
-{{ Fill in the Synopsis }}
+Creates a `ClientRequestProperties` object.
 
 ## SYNTAX
 
@@ -27,23 +27,50 @@ New-KustoClientRequestProperties
 
 ## DESCRIPTION
 
-{{ Fill in the Description }}
+The `New-KustoClientRequestProperties` cmdlet can be used to create a new `ClientRequestProperties` object
+to manage the interaction between client and service. This object can be later on passed as argument to the request cmdlets: [`Invoke-KustoControlCommand`](Invoke-KustoControlCommand.md) and [`Invoke-KustoQuery`](Invoke-KustoQuery.md).
+
+The object contains the following information:
+
+- [Request properties](https://learn.microsoft.com/en-us/kusto/api/netfx/client-request-properties?view=microsoft-fabric#request-properties): A mapping of specific options for customizing request behavior.
+- [Query parameters](https://learn.microsoft.com/en-us/kusto/api/netfx/client-request-properties?view=microsoft-fabric#query-parameters): A mapping of user-declared parameters that allow for secure query customization.
+- [Named properties](https://learn.microsoft.com/en-us/kusto/api/netfx/client-request-properties?view=microsoft-fabric#named-properties): Client request ID, application details, and user data, primarily used for debugging and tracing.
 
 ## EXAMPLES
 
-### Example 1
+### Example 1: Run a KQL Query with specified request properties
+
+```powershell
+$requestProps = New-KustoClientRequestProperties -NoTruncation -ServerTimeout '00:05:00'
+Invoke-KustoQuery 'myTable | project fooProp, barProp' -RequestProperties $requestProps
+```
+
+This example demonstrates how you can specify request properties for your query.
+
+- In this case `-NoTruncation` is particularly useful to overcome the 500k row limit on your query.
+- `-ServerTimeout '00:05:00'` allows the query to run for at least 5 minutes before timing out.
+
+### Example 2: Create a new `ClientRequestProperties` object with supported request properties
 
 ```powershell
-PS C:\> {{ Add example code here }}
+$requestProps = New-KustoClientRequestProperties -Options @{
+    query_language   = 'sql'
+    request_app_name = 'myApp'
+    norequesttimeout = $true
+}
 ```
 
-{{ Add example description here }}
+> [!TIP]
+>
+> Out of the supported request properties, this cmdlet only offers `-NoTruncation` (`notruncation`) and `-ServerTimeout` (`servertimeout`).
+> The `-Options` parameters offers adding extra options to your request that aren't by default available as a Parameter.
+> See [__Supported request properties__](https://learn.microsoft.com/en-us/kusto/api/rest/request-properties?view=microsoft-fabric#supported-request-properties) for the additional options.
 
 ## PARAMETERS
 
 ### -Application
 
-{{ Fill Application Description }}
+The name of the client application that makes the request. This value is used for tracing.
 
 ```yaml
 Type: String
@@ -59,7 +86,7 @@ Accept wildcard characters: False
 
 ### -ClientRequestId
 
-{{ Fill ClientRequestId Description }}
+An ID used to identify the request. This specification is helpful for debugging and may be required for specific scenarios like query cancellation.
 
 ```yaml
 Type: String
@@ -75,7 +102,7 @@ Accept wildcard characters: False
 
 ### -NoTruncation
 
-{{ Fill NoTruncation Description }}
+Disables truncation of query results returned to the caller.
 
 ```yaml
 Type: SwitchParameter
@@ -91,7 +118,7 @@ Accept wildcard characters: False
 
 ### -Options
 
-{{ Fill Options Description }}
+Specifies a Hashtable of additional [Supported request properties](https://learn.microsoft.com/en-us/kusto/api/rest/request-properties?view=microsoft-fabric#supported-request-properties) that aren't by default available as a Parameter.
 
 ```yaml
 Type: Hashtable
@@ -107,7 +134,7 @@ Accept wildcard characters: False
 
 ### -Parameters
 
-{{ Fill Parameters Description }}
+Specifies a Hashtable of [query parameters declaration statement](https://learn.microsoft.com/en-us/kusto/query/query-parameters-statement?view=microsoft-fabric) that are used to declare parameters for a Kusto Query Language (KQL) query.
 
 ```yaml
 Type: Hashtable
@@ -123,7 +150,7 @@ Accept wildcard characters: False
 
 ### -ServerTimeout
 
-{{ Fill ServerTimeout Description }}
+Overrides the default request timeout.
 
 ```yaml
 Type: TimeSpan
@@ -139,7 +166,7 @@ Accept wildcard characters: False
 
 ### -User
 
-{{ Fill User Description }}
+The identity of the user that makes the request. This value is used for tracing.
 
 ```yaml
 Type: String
@@ -153,22 +180,6 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -ProgressAction
-
-{{ Fill ProgressAction Description }}
-
-```yaml
-Type: ActionPreference
-Parameter Sets: (All)
-Aliases: proga
-
-Required: False
-Position: Named
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
-```
-
 ### CommonParameters
 
 This cmdlet supports the common parameters.
@@ -185,3 +196,9 @@ For more information, see [about_CommonParameters](http://go.microsoft.com/fwlin
 ## NOTES
 
 ## RELATED LINKS
+
+[Kusto Data ClientRequestProperties class](https://learn.microsoft.com/en-us/kusto/api/netfx/client-request-properties?view=microsoft-fabric)
+
+[Query parameters declaration statement](https://learn.microsoft.com/en-us/kusto/query/query-parameters-statement?view=microsoft-fabric)
+
+[Request properties](https://learn.microsoft.com/en-us/kusto/api/rest/request-properties?view=microsoft-fabric)

src/PowerShellKusto/Commands/NewKustoClientRequestPropertiesCommand.cs

@@ -34,7 +34,7 @@ public sealed class NewKustoClientRequestPropertiesCommand : PSCmdlet
 
     [Parameter]
     [ValidateTimespan]
-    public TimeSpan ServerTimeout { get; set; } = TimeSpan.FromSeconds(60);
+    public TimeSpan? ServerTimeout { get; set; }
 
     protected override void EndProcessing()
     {
@@ -60,8 +60,16 @@ protected override void EndProcessing()
             }
         }
 
-        properties.SetOption(ClientRequestProperties.OptionNoTruncation, NoTruncation);
-        properties.SetOption(ClientRequestProperties.OptionServerTimeout, ServerTimeout);
+        if (ServerTimeout is not null)
+        {
+            properties.SetOption(ClientRequestProperties.OptionServerTimeout, ServerTimeout);
+        }
+
+        if (NoTruncation)
+        {
+            properties.SetOption(ClientRequestProperties.OptionNoTruncation, NoTruncation);
+        }
+
         WriteObject(properties);
     }
 }