| | | 1 | | <# |
| | | 2 | | .SYNOPSIS |
| | | 3 | | Adds session state services and middleware to the Kestrun server. |
| | | 4 | | .DESCRIPTION |
| | | 5 | | Configures the Kestrun server to use session state for incoming requests. |
| | | 6 | | .PARAMETER Server |
| | | 7 | | The Kestrun server instance to configure. If not specified, the current server instance is used. |
| | | 8 | | .PARAMETER Options |
| | | 9 | | The session options to configure. If not specified, default options are used. |
| | | 10 | | .PARAMETER Cookie |
| | | 11 | | The cookie configuration to use. If not specified, default cookie settings are applied. |
| | | 12 | | Can be created with New-KrCookieBuilder and passed via pipeline. |
| | | 13 | | .PARAMETER IdleTimeout |
| | | 14 | | The idle timeout in seconds after which the session will expire. If not specified, the default is 20 minutes. |
| | | 15 | | .PARAMETER IOTimeout |
| | | 16 | | The IO timeout in seconds for session operations. If not specified, the default is 10 seconds. |
| | | 17 | | .PARAMETER NoDistributedMemoryCache |
| | | 18 | | If specified, the cmdlet will not add a default in-memory distributed cache. |
| | | 19 | | This is useful if you plan to add your own distributed cache implementation. |
| | | 20 | | The cmdlet will check if a distributed cache is already registered before adding the default. |
| | | 21 | | .PARAMETER MemoryCacheOptions |
| | | 22 | | The configuration options for the in-memory distributed cache. If not specified, default options are used. |
| | | 23 | | .PARAMETER PassThru |
| | | 24 | | If specified, the cmdlet returns the modified server instance after configuration. |
| | | 25 | | .EXAMPLE |
| | | 26 | | Add-KrSession -Server $myServer -Options $mySessionOptions |
| | | 27 | | Adds session state services and middleware to the specified Kestrun server with the provided options. |
| | | 28 | | .EXAMPLE |
| | | 29 | | Add-KrSession -IdleTimeout 30 -IOTimeout 15 |
| | | 30 | | Configures session state with a 30-minute idle timeout and a 15-second IO timeout. |
| | | 31 | | .EXAMPLE |
| | | 32 | | $cookie = New-KrCookieBuilder -Name 'SessionCookie' -HttpOnly -SameSite Lax |
| | | 33 | | Add-KrSession -Cookie $cookie -IdleTimeout 25 |
| | | 34 | | Configures session state with a 25-minute idle timeout and a cookie named 'SessionCookie'. |
| | | 35 | | .EXAMPLE |
| | | 36 | | New-KrCookieBuilder -Name 'SessionCookie' -HttpOnly -SameSite Lax | |
| | | 37 | | Add-KrSession -IdleTimeout 25 |
| | | 38 | | Configures session state with a 25-minute idle timeout and a cookie named 'SessionCookie' created via pipeline. |
| | | 39 | | .EXAMPLE |
| | | 40 | | Add-KrSession -NoDistributedMemoryCache |
| | | 41 | | Configures session state without adding a default in-memory distributed cache. Useful if you plan to add your ow |
| | | 42 | | .EXAMPLE |
| | | 43 | | $MemoryCacheOptions= [Microsoft.Extensions.Caching.Memory.MemoryDistributedCacheOptions]::new() |
| | | 44 | | $MemoryCacheOptions.SizeLimit = 1024 |
| | | 45 | | $MemoryCacheOptions.ExpirationScanFrequency = [TimeSpan]::FromMinutes(5) |
| | | 46 | | Add-KrSession -MemoryCacheOptions $MemoryCacheOptions |
| | | 47 | | Configures session state and adds a distributed memory cache with a size limit of 1024 bytes and an expiration s |
| | | 48 | | .NOTES |
| | | 49 | | This cmdlet is part of the Kestrun PowerShell module and is used to configure session state for Kestrun servers. |
| | | 50 | | .LINK |
| | | 51 | | https://docs.kestrun.dev/docs/powershell/kestrun/middleware |
| | | 52 | | #> |
| | | 53 | | function Add-KrSession { |
| | | 54 | | [KestrunRuntimeApi('Definition')] |
| | | 55 | | [CmdletBinding(defaultParameterSetName = 'Items')] |
| | | 56 | | [OutputType([Kestrun.Hosting.KestrunHost])] |
| | | 57 | | param( |
| | | 58 | | [Parameter(Mandatory = $false, ValueFromPipeline = $true)] |
| | | 59 | | [Kestrun.Hosting.KestrunHost]$Server, |
| | | 60 | | |
| | | 61 | | [Parameter(Mandatory = $true, ParameterSetName = 'Options')] |
| | | 62 | | [Microsoft.AspNetCore.Builder.SessionOptions]$Options, |
| | | 63 | | |
| | | 64 | | [Parameter(ParameterSetName = 'Items')] |
| | | 65 | | [Microsoft.AspNetCore.Http.CookieBuilder]$Cookie, |
| | | 66 | | |
| | | 67 | | [Parameter(ParameterSetName = 'Items')] |
| | | 68 | | [ValidateRange(1, [int]::MaxValue)] |
| | | 69 | | [int]$IdleTimeout, |
| | | 70 | | |
| | | 71 | | [Parameter(ParameterSetName = 'Items')] |
| | | 72 | | [ValidateRange(1, [int]::MaxValue)] |
| | | 73 | | [int]$IOTimeout, |
| | | 74 | | |
| | | 75 | | [Parameter()] |
| | | 76 | | [switch]$NoDistributedMemoryCache, |
| | | 77 | | |
| | | 78 | | [Parameter()] |
| | | 79 | | [Microsoft.Extensions.Caching.Memory.MemoryDistributedCacheOptions]$MemoryCacheOptions, |
| | | 80 | | |
| | | 81 | | [Parameter()] |
| | | 82 | | [switch]$PassThru |
| | | 83 | | ) |
| | | 84 | | begin { |
| | | 85 | | # Ensure the server instance is resolved |
| | 0 | 86 | | $Server = Resolve-KestrunServer -Server $Server |
| | | 87 | | } |
| | | 88 | | process { |
| | 0 | 89 | | if ($PSCmdlet.ParameterSetName -eq 'Items') { |
| | 0 | 90 | | $Options = [Microsoft.AspNetCore.Builder.SessionOptions]::new() |
| | | 91 | | |
| | 0 | 92 | | if ($PsBoundParameters.ContainsKey('IdleTimeout')) { |
| | 0 | 93 | | $Options.IdleTimeout = [TimeSpan]::FromSeconds($IdleTimeout) |
| | | 94 | | } |
| | 0 | 95 | | if ($PsBoundParameters.ContainsKey('IOTimeout')) { |
| | 0 | 96 | | $Options.IOTimeout = [TimeSpan]::FromSeconds($IOTimeout) |
| | | 97 | | } |
| | 0 | 98 | | if ($PsBoundParameters.ContainsKey('Cookie')) { |
| | 0 | 99 | | $Options.Cookie = $Cookie |
| | | 100 | | } |
| | | 101 | | } |
| | | 102 | | # If NoDistributedMemoryCache is not specified, and no distributed cache is registered, ensure a distributed mem |
| | 0 | 103 | | if ((-not $NoDistributedMemoryCache.IsPresent) -and |
| | 0 | 104 | | (-not $Server.IsServiceRegistered([Microsoft.Extensions.Caching.Distributed.IDistributedCache])) |
| | | 105 | | ) { |
| | | 106 | | # Add a default in-memory distributed cache if none exists |
| | 0 | 107 | | [Kestrun.Hosting.KestrunHostSessionExtensions]::AddDistributedMemoryCache($Server, $MemoryCacheOptions) | Ou |
| | | 108 | | } |
| | | 109 | | |
| | | 110 | | # Add the Session service to the server |
| | 0 | 111 | | [Kestrun.Hosting.KestrunHostSessionExtensions]::AddSession($Server, $Options) | Out-Null |
| | | 112 | | |
| | 0 | 113 | | if ($PassThru.IsPresent) { |
| | | 114 | | # if the PassThru switch is specified, return the modified server instance |
| | 0 | 115 | | return $Server |
| | | 116 | | } |
| | | 117 | | } |
| | | 118 | | } |