| | | 1 | | <# |
| | | 2 | | .SYNOPSIS |
| | | 3 | | Adds a form option to the Kestrun server. |
| | | 4 | | .DESCRIPTION |
| | | 5 | | This function creates and adds a form option to the Kestrun server's form options collection. |
| | | 6 | | It allows you to specify various parameters for the form option, such as name, description, |
| | | 7 | | allowed content types, upload path, and part rules. |
| | | 8 | | .PARAMETER Name |
| | | 9 | | The name of the form option. |
| | | 10 | | If not provided, a unique name will be generated as "FormOption_{GUID}". Also used as the key |
| | | 11 | | when registering the form option in the server's form options collection. |
| | | 12 | | If not unique, the registration will fail and $null will be returned. |
| | | 13 | | If not provided, the form option will still be created and returned, but not registered. |
| | | 14 | | .PARAMETER PartRules |
| | | 15 | | An array of form part rules associated with the form option. |
| | | 16 | | Can be provided via pipeline input. |
| | | 17 | | .PARAMETER Description |
| | | 18 | | A description of the form option. |
| | | 19 | | .PARAMETER AllowUnknownRequestContentType |
| | | 20 | | Indicates whether to allow unknown request content types. |
| | | 21 | | .PARAMETER AllowedRequestContentTypes |
| | | 22 | | An array of allowed request content types for the form option. |
| | | 23 | | .PARAMETER DefaultUploadPath |
| | | 24 | | The default upload path for files. |
| | | 25 | | .PARAMETER ComputeSha256 |
| | | 26 | | Indicates whether to compute the SHA-256 hash of uploaded files. |
| | | 27 | | .PARAMETER EnablePartDecompression |
| | | 28 | | Indicates whether to enable decompression of parts. |
| | | 29 | | .PARAMETER AllowedPartContentEncodings |
| | | 30 | | An array of allowed content encodings for parts. |
| | | 31 | | .PARAMETER MaxDecompressedBytesPerPart |
| | | 32 | | The maximum number of decompressed bytes per part. |
| | | 33 | | .PARAMETER RejectUnknownContentEncoding |
| | | 34 | | Indicates whether to reject unknown content encodings. |
| | | 35 | | .PARAMETER Logger |
| | | 36 | | The logger to use for logging. |
| | | 37 | | .PARAMETER MaxRequestBodyBytes |
| | | 38 | | The maximum size in bytes for the request body. |
| | | 39 | | .PARAMETER MaxPartBodyBytes |
| | | 40 | | The maximum size in bytes for each part body. |
| | | 41 | | .PARAMETER MaxParts |
| | | 42 | | The maximum number of parts allowed in the form. |
| | | 43 | | .PARAMETER MaxHeaderBytesPerPart |
| | | 44 | | The maximum size in bytes for headers per part. |
| | | 45 | | .PARAMETER MaxFieldValueBytes |
| | | 46 | | The maximum size in bytes for field values. |
| | | 47 | | .PARAMETER MaxNestingDepth |
| | | 48 | | The maximum nesting depth for multipart forms. |
| | | 49 | | .PARAMETER PassThru |
| | | 50 | | If specified, the cmdlet will return the created form option. |
| | | 51 | | If a Name is not provided, the created form option will always be returned. |
| | | 52 | | .EXAMPLE |
| | | 53 | | Add-KrFormOption -Name 'fileUpload' -DefaultUploadPath 'C:\Uploads' -ComputeSha256 -PartRules $rules |
| | | 54 | | This example adds a form option named 'fileUpload' with a default upload path of 'C:\Uploads', |
| | | 55 | | enables SHA-256 computation, and associates the specified part rules. |
| | | 56 | | .EXAMPLE |
| | | 57 | | New-KrFormPartRule -Name 'file' -Required -AllowedContentTypes 'text/plain'| |
| | | 58 | | Add-KrFormOption -Name 'textFileUpload' -PassThru |
| | | 59 | | This example creates a form part rule for a required text file and adds it to a new form option |
| | | 60 | | named 'textFileUpload'. |
| | | 61 | | .NOTES |
| | | 62 | | This function is part of the Kestrun.Forms module and is used to define form options. |
| | | 63 | | #> |
| | | 64 | | function Add-KrFormOption { |
| | | 65 | | [KestrunRuntimeApi('Definition')] |
| | | 66 | | [CmdletBinding()] |
| | | 67 | | [OutputType([Kestrun.Forms.KrFormOptions])] |
| | | 68 | | param( |
| | | 69 | | [Parameter(ValueFromPipeline = $true)] |
| | | 70 | | [Kestrun.Forms.KrFormPartRule[]] $PartRules, |
| | | 71 | | |
| | | 72 | | [Parameter()] |
| | | 73 | | [string] $Name, |
| | | 74 | | |
| | | 75 | | [Parameter()] |
| | | 76 | | [string] $Description, |
| | | 77 | | |
| | | 78 | | [Parameter()] |
| | | 79 | | [switch] $AllowUnknownRequestContentType, |
| | | 80 | | |
| | | 81 | | [Parameter()] |
| | 0 | 82 | | [string[]] $AllowedRequestContentTypes = @('multipart/form-data'), |
| | | 83 | | |
| | | 84 | | [Parameter()] |
| | | 85 | | [string] $DefaultUploadPath, |
| | | 86 | | |
| | | 87 | | [Parameter()] |
| | | 88 | | [switch] $ComputeSha256, |
| | | 89 | | |
| | | 90 | | [Parameter()] |
| | | 91 | | [switch] $EnablePartDecompression, |
| | | 92 | | |
| | | 93 | | [Parameter()] |
| | | 94 | | [string[]] $AllowedPartContentEncodings, |
| | | 95 | | |
| | | 96 | | [Parameter()] |
| | | 97 | | [long] $MaxDecompressedBytesPerPart, |
| | | 98 | | |
| | | 99 | | [Parameter()] |
| | | 100 | | [switch] $RejectUnknownContentEncoding, |
| | | 101 | | |
| | | 102 | | [Parameter()] |
| | | 103 | | [Serilog.ILogger] $Logger, |
| | | 104 | | |
| | | 105 | | # Limits (optional) |
| | | 106 | | [Parameter()] |
| | | 107 | | [long] $MaxRequestBodyBytes, |
| | | 108 | | |
| | | 109 | | [Parameter()] |
| | | 110 | | [long] $MaxPartBodyBytes , |
| | | 111 | | |
| | | 112 | | [Parameter()] |
| | | 113 | | [int] $MaxParts, |
| | | 114 | | |
| | | 115 | | [Parameter()] |
| | | 116 | | [int] $MaxHeaderBytesPerPart, |
| | | 117 | | |
| | | 118 | | [Parameter()] |
| | | 119 | | [long] $MaxFieldValueBytes, |
| | | 120 | | |
| | | 121 | | [Parameter()] |
| | | 122 | | [int] $MaxNestingDepth, |
| | | 123 | | |
| | | 124 | | [Parameter()] |
| | | 125 | | [switch] $PassThru |
| | | 126 | | |
| | | 127 | | ) |
| | | 128 | | begin { |
| | 0 | 129 | | $Server = Resolve-KestrunServer |
| | | 130 | | |
| | 0 | 131 | | $Options = [Kestrun.Forms.KrFormOptions]::new() |
| | | 132 | | |
| | 0 | 133 | | if ($PSBoundParameters.ContainsKey('Description')) { |
| | 0 | 134 | | $Options.Description = $Description |
| | | 135 | | } |
| | 0 | 136 | | if ($PSBoundParameters.ContainsKey('AllowedRequestContentTypes')) { |
| | | 137 | | # The underlying C# property is KrFormOptions.AllowedContentTypes. |
| | | 138 | | # Keep backward compatibility if an older assembly exposes AllowedRequestContentTypes. |
| | 0 | 139 | | if ($Options.PSObject.Properties.Match('AllowedContentTypes').Count -gt 0) { |
| | 0 | 140 | | $Options.AllowedContentTypes.Clear() |
| | 0 | 141 | | $Options.AllowedContentTypes.AddRange($AllowedRequestContentTypes) |
| | 0 | 142 | | } elseif ($Options.PSObject.Properties.Match('AllowedRequestContentTypes').Count -gt 0) { |
| | 0 | 143 | | $Options.AllowedRequestContentTypes.Clear() |
| | 0 | 144 | | $Options.AllowedRequestContentTypes.AddRange($AllowedRequestContentTypes) |
| | | 145 | | } else { |
| | 0 | 146 | | throw 'KrFormOptions does not expose AllowedContentTypes/AllowedRequestContentTypes. Ensure Kestrun modu |
| | | 147 | | } |
| | | 148 | | } |
| | 0 | 149 | | if ($PSBoundParameters.ContainsKey('AllowUnknownRequestContentType')) { |
| | 0 | 150 | | $Options.RejectUnknownRequestContentType = -not $AllowUnknownRequestContentType.IsPresent |
| | | 151 | | } |
| | 0 | 152 | | if ($PSBoundParameters.ContainsKey('DefaultUploadPath')) { |
| | 0 | 153 | | $Options.DefaultUploadPath = $DefaultUploadPath |
| | | 154 | | } |
| | 0 | 155 | | if ($PSBoundParameters.ContainsKey('ComputeSha256')) { |
| | 0 | 156 | | $Options.ComputeSha256 = $ComputeSha256.IsPresent |
| | | 157 | | } |
| | 0 | 158 | | if ($PSBoundParameters.ContainsKey('EnablePartDecompression')) { |
| | 0 | 159 | | $Options.EnablePartDecompression = $EnablePartDecompression.IsPresent |
| | | 160 | | } |
| | 0 | 161 | | if ($PSBoundParameters.ContainsKey('AllowedPartContentEncodings')) { |
| | 0 | 162 | | $Options.AllowedPartContentEncodings.Clear() |
| | 0 | 163 | | $Options.AllowedPartContentEncodings.AddRange($AllowedPartContentEncodings) |
| | | 164 | | } |
| | 0 | 165 | | if ($PSBoundParameters.ContainsKey('MaxDecompressedBytesPerPart')) { |
| | 0 | 166 | | $Options.MaxDecompressedBytesPerPart = $MaxDecompressedBytesPerPart |
| | | 167 | | } |
| | 0 | 168 | | if ($PSBoundParameters.ContainsKey('RejectUnknownContentEncoding')) { |
| | 0 | 169 | | $Options.RejectUnknownContentEncoding = $RejectUnknownContentEncoding.IsPresent |
| | | 170 | | } |
| | | 171 | | |
| | 0 | 172 | | if ($PSBoundParameters.ContainsKey('Logger')) { |
| | 0 | 173 | | $Options.Logger = $Logger |
| | | 174 | | } else { |
| | 0 | 175 | | $Options.Logger = $Server.Logger |
| | | 176 | | } |
| | | 177 | | |
| | | 178 | | # Limits |
| | 0 | 179 | | if ($PSBoundParameters.ContainsKey('MaxRequestBodyBytes')) { |
| | 0 | 180 | | $Options.Limits.MaxRequestBodyBytes = $MaxRequestBodyBytes |
| | | 181 | | } |
| | 0 | 182 | | if ($PSBoundParameters.ContainsKey('MaxPartBodyBytes')) { |
| | 0 | 183 | | $Options.Limits.MaxPartBodyBytes = $MaxPartBodyBytes |
| | | 184 | | } |
| | 0 | 185 | | if ($PSBoundParameters.ContainsKey('MaxParts')) { |
| | 0 | 186 | | $Options.Limits.MaxParts = $MaxParts |
| | | 187 | | } |
| | 0 | 188 | | if ($PSBoundParameters.ContainsKey('MaxHeaderBytesPerPart')) { |
| | 0 | 189 | | $Options.Limits.MaxHeaderBytesPerPart = $MaxHeaderBytesPerPart |
| | | 190 | | } |
| | 0 | 191 | | if ($PSBoundParameters.ContainsKey('MaxFieldValueBytes')) { |
| | 0 | 192 | | $Options.Limits.MaxFieldValueBytes = $MaxFieldValueBytes |
| | | 193 | | } |
| | 0 | 194 | | if ($PSBoundParameters.ContainsKey('MaxNestingDepth')) { |
| | 0 | 195 | | $Options.Limits.MaxNestingDepth = $MaxNestingDepth |
| | | 196 | | } |
| | | 197 | | |
| | | 198 | | # Register the option |
| | 0 | 199 | | if ($PSBoundParameters.ContainsKey('Name')) { |
| | 0 | 200 | | $Options.Name = $Name |
| | | 201 | | # Register the option in the server's form options collection |
| | 0 | 202 | | if (-not $Server.AddFormOption($Options)) { |
| | 0 | 203 | | return $null |
| | | 204 | | } |
| | | 205 | | # Return the created options if PassThru is specified |
| | 0 | 206 | | if (-not $PassThru.IsPresent) { |
| | | 207 | | return |
| | | 208 | | } |
| | | 209 | | } else { |
| | | 210 | | # Generate a unique name if not provided |
| | 0 | 211 | | $Options.Name = "FormOption_$([System.Guid]::NewGuid().ToString())" |
| | | 212 | | } |
| | | 213 | | } |
| | | 214 | | process { |
| | 0 | 215 | | if ($PSBoundParameters.ContainsKey('PartRules')) { |
| | 0 | 216 | | $Options.Rules.Clear() |
| | 0 | 217 | | foreach ($rule in $PartRules) { |
| | 0 | 218 | | $Options.Rules.Add($rule) |
| | | 219 | | } |
| | | 220 | | } |
| | | 221 | | } |
| | | 222 | | end { |
| | 0 | 223 | | if ( $PassThru.IsPresent -or -not $PSBoundParameters.ContainsKey('Name')) { |
| | 0 | 224 | | return $Options |
| | | 225 | | } |
| | | 226 | | } |
| | | 227 | | } |