New-DbaAgentSchedule: Add new parameter FrequencyText (#9847)

Author: andreasjordan

public/New-DbaAgentSchedule.ps1

@@ -88,6 +88,23 @@ function New-DbaAgentSchedule {
 
         FrequencyRecurrenceFactor is used only if FrequencyType is "Weekly", "Monthly" or "MonthlyRelative".
 
+    .PARAMETER FrequencyText
+        Describe common frequencies as a text. Sample text:
+
+        Every minute
+        Every 5 minutes
+        Every 10 minutes starting at 00:02:30
+        Every hour
+        Every 2 hours
+        Every 4 hours starting at 02:00:00
+        Every day at 05:00:00
+        Every sunday at 02:00:00
+
+        This is the used regex: every(\s+(?<interval>\d+))?\s+(?<unit>minute|hour|day|sunday|monday|tuesday|wednesday|thursday|friday|saturday)s?(\s+starting)?(\s+at\s+(?<start>\d\d:\d\d:\d\d))?
+
+        If parameter Schedule is not provided, the FrequencyText will be used as the name of the schedule.
+        Parameter Force will be set to $true.
+
     .PARAMETER StartDate
         The earliest date this schedule can execute jobs, formatted as yyyyMMdd (e.g., "20240315" for March 15, 2024).
         Use this to delay schedule activation until a future date or to document when recurring maintenance should begin.
@@ -157,6 +174,12 @@ function New-DbaAgentSchedule {
         PS C:\> New-DbaAgentSchedule -SqlInstance sstad-pc -Schedule RunWeekly -FrequencyType Weekly -FrequencyInterval Sunday -StartTime 010000 -Force
 
         Create a schedule that will run jobs once a week on Sunday @ 1:00AM
+
+    .EXAMPLE
+        PS C:\> New-DbaAgentSchedule -SqlInstance sstad-pc -FrequencyText 'Every sunday at 02:00:00'
+
+        Create a schedule with the name "Every sunday at 02:00:00" that will run jobs once a week on Sunday @ 2:00AM
+
     #>
     [CmdletBinding(SupportsShouldProcess, ConfirmImpact = "Low")]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseOutputTypeCorrectly", "", Justification = "PSSA Rule Ignored by BOH")]
@@ -176,6 +199,7 @@ function New-DbaAgentSchedule {
         [ValidateSet('Unused', 'First', 'Second', 'Third', 'Fourth', 'Last')]
         [object]$FrequencyRelativeInterval,
         [int]$FrequencyRecurrenceFactor,
+        [string]$FrequencyText,
         [string]$StartDate,
         [string]$EndDate,
         [string]$StartTime,
@@ -188,6 +212,42 @@ function New-DbaAgentSchedule {
     begin {
         if ($Force) { $ConfirmPreference = 'none' }
 
+        if ($FrequencyText) {
+            if ($FrequencyText -match 'every(\s+(?<interval>\d+))?\s+(?<unit>minute|hour|day|sunday|monday|tuesday|wednesday|thursday|friday|saturday)s?(\s+starting)?(\s+at\s+(?<start>\d\d:\d\d:\d\d))?') {
+                $textInterval = $Matches['interval']
+                $textUnit     = $Matches['unit']
+                $textStart    = $Matches['start']
+
+                if (-not $textInterval) {
+                    $textInterval = 1
+                }
+
+                if ($textUnit -in 'minute', 'hour', 'day') {
+                    $FrequencyType = 'Daily'
+                    if ($textUnit -in 'minute', 'hour') {
+                        $FrequencySubdayType = $textUnit
+                        $FrequencySubdayInterval = $textInterval
+                    }
+                } else {
+                    $FrequencyType = 'Weekly'
+                    $FrequencyInterval = $textUnit
+                }
+
+                if ($textStart) {
+                    $StartTime = $textStart.Replace(':', '')
+                }
+
+                if (-not $Schedule) {
+                    $Schedule = $FrequencyText
+                }
+
+                $Force = $true
+            } else {
+                Stop-Function -Message "FrequencyText can not be parsed."
+                return
+            }
+        }
+
         if ($FrequencyType -eq "Daily" -and -not $FrequencyInterval) {
             $FrequencyInterval = 1
         }

tests/New-DbaAgentSchedule.Tests.ps1

@@ -22,6 +22,7 @@ Describe $CommandName -Tag UnitTests {
                 "FrequencySubdayInterval",
                 "FrequencyRelativeInterval",
                 "FrequencyRecurrenceFactor",
+                "FrequencyText",
                 "StartDate",
                 "EndDate",
                 "StartTime",
@@ -267,4 +268,41 @@ Describe $CommandName -Tag IntegrationTests {
             }
         }
     }
+
+    Context "Should create schedules based on frequency texts" {
+        It "Should create a schedule for: Every minute" {
+            $results = New-DbaAgentSchedule -SqlInstance $TestConfig.instance2 -FrequencyText 'Every minute'
+            $results.Name | Should -Be 'Every minute'
+            $results.Description | Should -BeLike 'Occurs every day every 1 minute(s) between 12:00:00 AM and 11:59:59 PM*'
+            $results | Remove-DbaAgentSchedule
+        }
+
+        It "Should create a schedule for: Every 10 minutes starting at 00:02:30" {
+            $results = New-DbaAgentSchedule -SqlInstance $TestConfig.instance2 -FrequencyText 'Every 10 minutes starting at 00:02:30'
+            $results.Name | Should -Be 'Every 10 minutes starting at 00:02:30'
+            $results.Description | Should -BeLike 'Occurs every day every 10 minute(s) between 12:02:30 AM and 11:59:59 PM*'
+            $results | Remove-DbaAgentSchedule
+        }
+
+        It "Should create a schedule for: Every 2 hours" {
+            $results = New-DbaAgentSchedule -SqlInstance $TestConfig.instance2 -FrequencyText 'Every 2 hours'
+            $results.Name | Should -Be 'Every 2 hours'
+            $results.Description | Should -BeLike 'Occurs every day every 2 hour(s) between 12:00:00 AM and 11:59:59 PM*'
+            $results | Remove-DbaAgentSchedule
+        }
+
+        It "Should create a schedule for: Every day at 05:00:00" {
+            $results = New-DbaAgentSchedule -SqlInstance $TestConfig.instance2 -FrequencyText 'Every day at 05:00:00'
+            $results.Name | Should -Be 'Every day at 05:00:00'
+            $results.Description | Should -BeLike 'Occurs every day at 5:00:00 AM*'
+            $results | Remove-DbaAgentSchedule
+        }
+
+        It "Should create a schedule for: Every sunday at 02:00:00" {
+            $results = New-DbaAgentSchedule -SqlInstance $TestConfig.instance2 -FrequencyText 'Every sunday at 02:00:00'
+            $results.Name | Should -Be 'Every sunday at 02:00:00'
+            $results.Description | Should -BeLike 'Occurs every week on Sunday at 2:00:00 AM*'
+            $results | Remove-DbaAgentSchedule
+        }
+    }
 }