File Server & Directory Browsing

Serve a directory tree with optional HTML listings and custom MIME mappings.

Prerequisites: see Introduction.

Full source 

<#
    Sample Kestrun Server on how to configure a static file server.
    These examples demonstrate how to configure static routes with directory browsing in a Kestrun server.
    FileName: 3.2-File-Server.ps1
#>

# Import the Kestrun module
Install-PSResource -Name Kestrun

# Initialize Kestrun root directory
# the default value is $PWD
# This is recommended in order to use relative paths without issues
Initialize-KrRoot -Path $PSScriptRoot

# Create a new Kestrun server
New-KrServer -Name "Simple Server"

# Add a listener on port 5000 and IP address 127.0.0.1 (localhost)
Add-KrListener -Port 5000 -IPAddress ([IPAddress]::Loopback)

# Define the content type map to add to the default set
$map = @{
    ".yaml" = "application/x-yaml"
    ".yml" = "application/x-yaml"
    ".ps1" = "text/plain"
}

# Add a file server with browsing enabled
Add-KrFileServer -RequestPath '/' -RootPath '.\Assets\wwwroot' -EnableDirectoryBrowsing -ContentTypeMap $map

# Enable Kestrun configuration
Enable-KrConfiguration

# Start the server asynchronously
Start-KrServer

Step-by-step

  1. Root initialization: Initialize-KrRoot ensures '.\Assets\wwwroot' is resolved relative to the script.
  2. Listener: same loopback listener as earlier samples.
  3. Content type mapping: A hashtable $map extends built‑in MIME mappings (e.g., adds YAML, forces .ps1 to text/plain so scripts display rather than download/execute).
  4. File server registration: Add-KrFileServer -RequestPath '/' ... -ContentTypeMap $map mounts the root of the hosted site and applies the custom provider.
  5. Directory browsing: -EnableDirectoryBrowsing renders an HTML listing when a request targets a directory without a default document.
  6. Start & serve: Enable-KrConfiguration then Start-KrServer activates the service.

File Server vs Static Files Service

Aspect Add-KrStaticFilesService Add-KrFileServer
Purpose Serve static files under a path prefix Serve files and optionally list directories
Directory listing Not built-in Supported via -EnableDirectoryBrowsing
Typical mount path A sub-path (e.g., /assets) Root (/) or sub-path needing browsing
Minimal configuration -RequestPath + -RootPath Same, plus optional browsing flag
Custom MIME map Via options object (advanced) Simple -ContentTypeMap hashtable parameter
Serve unknown types Flag available (-ServeUnknownFileTypes on options) -ServeUnknownFileTypes switch (use sparingly)
Use case Performance asset bundle File repository / docs / ad-hoc downloads / exploratory dirs

Choose Add-KrStaticFilesService for performance-focused asset hosting (no listing page). Choose Add-KrFileServer when you want users to navigate folders or you need a quick file drop.

Try it

Start the server 

. .\docs\pwsh\tutorial\examples\3.2-File-Server.ps1

Browse

Open http://127.0.0.1:5000/ in a browser. You should see an index (listing) including the sample files you created under Assets/wwwroot (e.g., /files/sample.txt, /files/data.json, images, docs, etc.). YAML files should now show Content-Type: application/x-yaml and .ps1 files as text/plain per the mapping.

Fetch examples (PowerShell) 

Invoke-WebRequest -Uri 'http://127.0.0.1:5000/files/sample.txt' | Select-Object -ExpandProperty Content
Invoke-WebRequest -Uri 'http://127.0.0.1:5000/files/data.json' | Select-Object -ExpandProperty Content

Security considerations

  • Mount only directories intended for public access.
  • Exclude secrets/build artifacts from the root path.
  • For large directories disable browsing in production unless needed.

Troubleshooting

Symptom Cause Fix
404 for expected file Wrong path or root misconfigured Verify physical file exists under RootPath; check Initialize-KrRoot usage.
Directory listing not shown -EnableDirectoryBrowsing omitted Re-register service with the flag or add it.
Incorrect MIME type Unrecognized extension Add a custom mapping if supported or rename file with standard extension.
Access to parent dirs Attempt to traverse with .. Requests should be safely rooted; ensure latest version if traversal appears.

Cmdlet references

Next

Previous: Serving Static Files
Next: Static Route Overrides
Skip ahead: Variable Routes