added auto-iteration mode cmdlets

Author: afroz429

generator/AWSPSGeneratorLib/Writers/SourceCode/CmdletSourceWriter.cs

@@ -64,7 +64,15 @@ public void Write(IndentedTextWriter writer)
             var methodDocumentation = DocumentationUtils.GetMethodDocumentation(methodInfo.DeclaringType, Operation.MethodName, MethodAnalysis.AssemblyDocumentation);
 
             if (autoIteration != null)
-                methodDocumentation += $"<br/><br/>{(Operation.LegacyPagination == ServiceOperation.LegacyPaginationType.DisablePagination ? $"In the AWS.Tools.{ServiceConfig.AssemblyName} module, t" : "T")}his cmdlet automatically pages all available results to the pipeline - parameters related to iteration are only needed if you want to manually control the paginated output. To disable autopagination, use -NoAutoIteration.";
+            {
+                methodDocumentation +=
+                    $"<br/><br/>{(Operation.LegacyPagination == ServiceOperation.LegacyPaginationType.DisablePagination ? $"In the AWS.Tools.{ServiceConfig.AssemblyName} module, t" : "T")}his cmdlet automatically pages all available results to the pipeline - parameters related to iteration are only needed if you want to manually control the paginated output. To disable autopagination, use -NoAutoIteration.";
+
+                if (autoIteration.SupportLegacyAutoIterationMode)
+                {
+                    methodDocumentation += " This cmdlet didn't autopaginate in V4, auto-pagination support was added in V5.";
+                }
+            }
 
             if (GetOperationObsoleteMessage(methodInfo) != null)
                 methodDocumentation += "<br/><br/>This operation is deprecated.";
@@ -523,6 +531,11 @@ public void WriteNoAutoIterationSwitchParam(IndentedTextWriter writer)
             writer.WriteLine("/// By default the cmdlet will auto-iterate and retrieve all results to the pipeline by performing multiple");
             writer.WriteLine($"/// service calls. If set, the cmdlet will retrieve only the next 'page' of results using the value of {startProperty.CmdletParameterName}");
             writer.WriteLine("/// as the start point.");
+            if (autoIteration.SupportLegacyAutoIterationMode)
+            {
+                writer.WriteLine("/// This cmdlet didn't autopaginate in V4. To preserve the V4 autopagination behavior for all cmdlets, run Set-AWSAutoIterationMode -IterationMode v4.");
+            }
+
             writer.WriteLine("/// </summary>");
             writer.WriteLine("[System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)]");
             writer.WriteLine("public SwitchParameter NoAutoIteration { get; set; }");
@@ -1366,7 +1379,7 @@ private void WriteIExecutorIterPattern1(IndentedTextWriter writer)
                 // disable auto-iteration for cmdlets that didn't have auto-iteration in v4 in legacy mode.
                 if (autoIteration.SupportLegacyAutoIterationMode)
                 {
-                    writer.WriteLine(@$"var _shouldAutoIterate = !(SessionState.PSVariable.GetValue(""AWS_POWERSHELL_AUTOITERATION_MODE"")?.ToString() == ""legacy"");");
+                    writer.WriteLine(@$"var _shouldAutoIterate = !(SessionState.PSVariable.GetValue(""AWSPowerShell_AutoIteration_Mode"")?.ToString() == ""v4"");");
                 }
 
                 writer.WriteLine();

modules/AWSPowerShell/Cmdlets/Account/Basic/Get-ACCTRegionList-Cmdlet.cs

@@ -31,7 +31,7 @@ namespace Amazon.PowerShell.Cmdlets.ACCT
 {
     /// <summary>
     /// Lists all the Regions for a given account and their respective opt-in statuses. Optionally,
-    /// this list can be filtered by the <c>region-opt-status-contains</c> parameter.
+    /// this list can be filtered by the <c>region-opt-status-contains</c> parameter.<br/><br/>This cmdlet automatically pages all available results to the pipeline - parameters related to iteration are only needed if you want to manually control the paginated output. To disable autopagination, use -NoAutoIteration. This cmdlet didn't autopaginate in V4, auto-pagination support was added in V5.
     /// </summary>
     [Cmdlet("Get", "ACCTRegionList")]
     [OutputType("Amazon.Account.Model.Region")]
@@ -91,10 +91,15 @@ public partial class GetACCTRegionListCmdlet : AmazonAccountClientCmdlet, IExecu
         /// see <a href="http://docs.aws.amazon.com/cli/latest/userguide/pagination.html">Pagination</a>
         /// in the <i>Amazon Web Services Command Line Interface User Guide</i>. </para>
         /// </para>
+        /// <para>
+        /// <br/><b>Note:</b> In AWSPowerShell and AWSPowerShell.NetCore this parameter is used to limit the total number of items returned by the cmdlet.
+        /// <br/>In AWS.Tools this parameter is simply passed to the service to specify how many items should be returned by each service call.
+        /// <br/>Pipe the output of this cmdlet into Select-Object -First to terminate retrieving data pages early and control the number of items returned.
+        /// </para>
         /// </summary>
         [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)]
-        [Alias("MaxResults")]
-        public System.Int32? MaxResult { get; set; }
+        [Alias("MaxItems","MaxResults")]
+        public int? MaxResult { get; set; }
         #endregion
 
         #region Parameter NextToken
@@ -104,6 +109,10 @@ public partial class GetACCTRegionListCmdlet : AmazonAccountClientCmdlet, IExecu
         /// a previously truncated response. For usage examples, see <a href="http://docs.aws.amazon.com/cli/latest/userguide/pagination.html">Pagination</a>
         /// in the <i>Amazon Web Services Command Line Interface User Guide</i>.</para>
         /// </para>
+        /// <para>
+        /// <br/><b>Note:</b> This parameter is only used if you are manually controlling output pagination of the service API call.
+        /// <br/>'NextToken' is only returned by the cmdlet when '-Select *' is specified. In order to manually control output pagination, set '-NextToken' to null for the first call then set the 'NextToken' using the same property output from the previous call for subsequent calls.
+        /// </para>
         /// </summary>
         [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)]
         public System.String NextToken { get; set; }
@@ -120,6 +129,17 @@ public partial class GetACCTRegionListCmdlet : AmazonAccountClientCmdlet, IExecu
         public string Select { get; set; } = "Regions";
         #endregion
 
+        #region Parameter NoAutoIteration
+        /// <summary>
+        /// By default the cmdlet will auto-iterate and retrieve all results to the pipeline by performing multiple
+        /// service calls. If set, the cmdlet will retrieve only the next 'page' of results using the value of NextToken
+        /// as the start point.
+        /// This cmdlet didn't autopaginate in V4. To preserve the V4 autopagination behavior for all cmdlets, run Set-AWSAutoIterationMode -IterationMode v4.
+        /// </summary>
+        [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)]
+        public SwitchParameter NoAutoIteration { get; set; }
+        #endregion
+        
         protected override void StopProcessing()
         {
             base.StopProcessing();
@@ -141,6 +161,15 @@ protected override void ProcessRecord()
             }
             context.AccountId = this.AccountId;
             context.MaxResult = this.MaxResult;
+            #if !MODULAR
+            if (ParameterWasBound(nameof(this.MaxResult)) && this.MaxResult.HasValue)
+            {
+                WriteWarning("AWSPowerShell and AWSPowerShell.NetCore use the MaxResult parameter to limit the total number of items returned by the cmdlet." +
+                    " This behavior is obsolete and will be removed in a future version of these modules. Pipe the output of this cmdlet into Select-Object -First to terminate" +
+                    " retrieving data pages early and control the number of items returned. AWS.Tools already implements the new behavior of simply passing MaxResult" +
+                    " to the service to specify how many items should be returned by each service call.");
+            }
+            #endif
             context.NextToken = this.NextToken;
             if (this.RegionOptStatusContain != null)
             {
@@ -159,7 +188,9 @@ protected override void ProcessRecord()
         public object Execute(ExecutorContext context)
         {
             var cmdletContext = context as CmdletContext;
-            // create request
+            var useParameterSelect = this.Select.StartsWith("^");
+            
+            // create request and set iteration invariants
             var request = new Amazon.Account.Model.ListRegionsRequest();
 
             if (cmdletContext.AccountId != null)
@@ -168,38 +199,59 @@ public object Execute(ExecutorContext context)
             }
             if (cmdletContext.MaxResult != null)
             {
-                request.MaxResults = cmdletContext.MaxResult.Value;
-            }
-            if (cmdletContext.NextToken != null)
-            {
-                request.NextToken = cmdletContext.NextToken;
+                request.MaxResults = AutoIterationHelpers.ConvertEmitLimitToServiceTypeInt32(cmdletContext.MaxResult.Value);
             }
             if (cmdletContext.RegionOptStatusContain != null)
             {
                 request.RegionOptStatusContains = cmdletContext.RegionOptStatusContain;
             }
 
-            CmdletOutput output;
+            // Initialize loop variant and commence piping
+            var _nextToken = cmdletContext.NextToken;
+            var _userControllingPaging = this.NoAutoIteration.IsPresent || ParameterWasBound(nameof(this.NextToken));
+            var _shouldAutoIterate = !(SessionState.PSVariable.GetValue("AWSPowerShell_AutoIteration_Mode")?.ToString() == "v4");
 
-            // issue call
             var client = Client ?? CreateClient(_CurrentCredentials, _RegionEndpoint);
-            try
+            do
             {
-                var response = CallAWSServiceOperation(client, request);
-                object pipelineOutput = null;
-                pipelineOutput = cmdletContext.Select(response, this);
-                output = new CmdletOutput
+                request.NextToken = _nextToken;
+                
+                CmdletOutput output;
+                
+                try
                 {
-                    PipelineOutput = pipelineOutput,
-                    ServiceResponse = response
-                };
-            }
-            catch (Exception e)
+                    
+                    var response = CallAWSServiceOperation(client, request);
+                    
+                    object pipelineOutput = null;
+                    if (!useParameterSelect)
+                    {
+                        pipelineOutput = cmdletContext.Select(response, this);
+                    }
+                    output = new CmdletOutput
+                    {
+                        PipelineOutput = pipelineOutput,
+                        ServiceResponse = response
+                    };
+                    
+                    _nextToken = response.NextToken;
+                }
+                catch (Exception e)
+                {
+                    output = new CmdletOutput { ErrorResponse = e };
+                }
+                
+                ProcessOutput(output);
+                
+            } while (!_userControllingPaging && _shouldAutoIterate && AutoIterationHelpers.HasValue(_nextToken));
+            
+            if (useParameterSelect)
             {
-                output = new CmdletOutput { ErrorResponse = e };
+                WriteObject(cmdletContext.Select(null, this));
             }
 
-            return output;
+            
+            return null;
         }
 
         public ExecutorContext CreateContext()
@@ -234,7 +286,7 @@ private Amazon.Account.Model.ListRegionsResponse CallAWSServiceOperation(IAmazon
         internal partial class CmdletContext : ExecutorContext
         {
             public System.String AccountId { get; set; }
-            public System.Int32? MaxResult { get; set; }
+            public int? MaxResult { get; set; }
             public System.String NextToken { get; set; }
             public List<System.String> RegionOptStatusContain { get; set; }
             public System.Func<Amazon.Account.Model.ListRegionsResponse, GetACCTRegionListCmdlet, object> Select { get; set; } =

modules/AWSPowerShell/Common/CommonCmdlets.cs

@@ -597,6 +597,80 @@ protected override void ProcessRecord()
                 noteProperty.Value = (bool)showSensitiveData.Value;
             }
 
+            result.Properties.Add(noteProperty);
+            WriteObject(result);
+        }
+    }
+
+/// <summary>
+/// Controls the auto-iteration behavior for AWS PowerShell cmdlets.
+/// Sets a shell variable that determines whether cmdlets use standard or v4 auto-iteration mode.
+/// In standard mode, all operations with pagination support will auto-iterate by default.
+/// In v4 mode, only operations that had auto-iteration in v4 will auto-iterate, maintaining backward compatibility.
+/// </summary>
+    [Cmdlet("Set", "AWSAutoIterationMode")]
+    [AWSCmdlet("Controls the auto-iteration behavior for AWS PowerShell cmdlets. Sets whether to use standard mode (all operations with pagination support auto-iterate) or v4 mode (only operations that had auto-iteration in v4 will auto-iterate).")]
+    [OutputType("None")]
+    public class SetAWSAutoIterationModeCmdlet : PSCmdlet
+    {
+        #region Parameter IterationMode
+
+        /// <summary>
+        /// Controls the auto-iteration behavior for AWS PowerShell cmdlets.
+        /// When set to 'standard' (default), all operations with pagination support will auto-iterate.
+        /// When set to 'v4', only operations that had auto-iteration in v4 will auto-iterate, maintaining backward compatibility.
+        /// </summary>
+        [Parameter(ValueFromPipelineByPropertyName = true, Mandatory = true)]
+        [ValidateSet("standard", "v4")]
+        public string IterationMode { get; set; }
+
+        #endregion
+
+        #region Parameter Scope
+        /// <summary>
+        /// <para>
+        /// Sets the scope of the shell variable AWSPowerShell_AutoIteration_Mode.
+        /// For details about variables scopes, see https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_scopes.
+        /// </para>
+        /// </summary>
+        [Parameter(ValueFromPipelineByPropertyName = true)]
+        public VariableScope Scope { get; set; }
+        #endregion
+
+        protected override void ProcessRecord()
+        {
+            base.ProcessRecord();
+            WriteVerbose($"Setting IterationMode to {IterationMode}");
+            string scope = MyInvocation.BoundParameters.ContainsKey("Scope") ? Scope.ToString() + ":" : "";
+
+            this.SessionState.PSVariable.Set(scope + SessionKeys.AWSAutoIterationMode, IterationMode);
+        }
+    }
+
+    /// <summary>
+    /// Returns the current auto-iteration mode setting that controls how cmdlets handle pagination.
+    /// This cmdlet returns the current value ('standard' or 'v4') indicating which auto-iteration mode is active.
+    /// </summary>
+    [Cmdlet("Get", "AWSAutoIterationMode")]
+    [AWSCmdlet("Gets the current auto-iteration mode setting that controls how cmdlets handle pagination.")]
+    [OutputType("PSObject")]
+    public class GetAWSAutoIterationModeCmdlet : PSCmdlet
+    {
+        protected override void ProcessRecord()
+        {
+            base.ProcessRecord();
+            var autoIterationMode= this.SessionState.PSVariable.Get(SessionKeys.AWSAutoIterationMode);
+            var result = new PSObject();
+
+            const string defaultAutoIterationMode = "standard";
+
+            var noteProperty = new PSNoteProperty("AutoIterationMode", defaultAutoIterationMode);
+
+            if (autoIterationMode != null)
+            {
+                noteProperty.Value = autoIterationMode.Value.ToString();
+            }
+            
             result.Properties.Add(noteProperty);
             WriteObject(result);
         }

modules/AWSPowerShell/Common/CredentialsArguments.cs

@@ -725,6 +725,7 @@ internal static class SessionKeys
         public const string AWSRegionVariableName = "StoredAWSRegion";
         public const string AWSShowSensitiveData = "AWSPowerShell_Show_Sensitive_Data";
         public const string AWSProxyVariableName = "AWSProxy";
+        public const string AWSAutoIterationMode = "AWSPowerShell_AutoIteration_Mode";
     }
 
     internal static class CredentialProfileOptionsExtractor

modules/ModularAWSPowerShell/AWS.Tools.Common.psd1

@@ -95,7 +95,9 @@ Alternative modules, AWSPowerShell.NetCore and AWSPowerShell, provide support fo
         'Clear-AWSDefaultConfiguration', 
         'Get-AWSPowerShellVersion', 
         'Set-AWSSensitiveDataConfiguration', 
-        'Get-AWSSensitiveDataConfiguration', 
+        'Get-AWSSensitiveDataConfiguration',
+        'Set-AWSAutoIterationMode', 
+        'Get-AWSAutoIterationMode',
         'New-AWSCredential', 
         'Set-AWSCredential', 
         'Clear-AWSCredential',