Home / .NET / Web Frameworks

A cross-platform, minimalist web framework for PowerShell

Polaris A cross-platform, minimalist web framework for PowerShell. Disclaimer Polaris is currently an unsupported, experimental, proof-of-concept. There is no current plan to turn it into a supported Microsoft pro
Information
Category: .NET / Web Frameworks
Watchers: 66
Star: 488
Fork: 110
Last update: Mar 20, 2023
Resource links
https://github.com/PowerShell/Polaris

Polaris

Join the chat at https://gitter.im/PowerShell/Polaris Build Status PowerShell Gallery

A cross-platform, minimalist web framework for PowerShell.

Disclaimer

Polaris is currently an unsupported, experimental, proof-of-concept. There is no current plan to turn it into a supported Microsoft product.

That being said, we do plan on continuing to experiment within this repository for the foreseeable future.

Example

New-PolarisGetRoute -Path "/helloworld" -Scriptblock {
    $Response.Send('Hello World!')
}

Start-Polaris

Why yet another web framework for PowerShell?

There have been a great list of other micro web frameworks written over the years (Thanks @jaykul for the list!).

Polaris' differentiation is that it is cross-platform and uses the .NET HttpListener class.

Getting Started

Prerequisites

Steps

From the PowerShell Gallery

PS > Install-Module -Name Polaris -Scope CurrentUser -Force

You can now try out the example above or checkout the site for more usage information!

From source

  1. Clone or download the zip of the repo
  2. Open PowerShell
  3. At this point, you can now run Import-Module ./Polaris.psd1

You can now try out the example above or checkout the site for more usage!

You can also run all the Pester tests by running Invoke-Pester in the test directory. You will need Pester version 4.1.0 or higher to run the tests on Linux or MacOS.

Documentation

Check out the docs folder or the site for a full API reference.

Troubleshooting / Questions

  • Twitter: #PSPolaris
  • Slack: See us in the #Polaris channel of the PowerShell Slack
  • GitHub Issues: Submit a bug / new feature idea / or just a question as a new GitHub issue

Roadmap

We have a few paths we are interested in taking. We hope the community helps direct us.

  • Expanding on the current implementation using HttpListener to deliver features you'd expect from projects ASP.NET or Expressjs (route parameters, query parameters, middleware, auth etc)
  • Investigating the use of Kestrel/ASP.NET Routing instead of HttpListener
  • Creating a routing domain-specific language (DSL) for isolating and running script blocks as routes. Drawing inspiration from Pester.

Feedback

This project is an experiment that has the possibility to grow into something great. We can't do that without great feedback from you.

If you have an idea or find a bug, join the discussions in the issues or create a new issue.

License

Polaris is licensed under the MIT License.

Maintainers

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

32 Open More issues
Closed

Investigate use or pure powershell

Considering powershell can natively instantiate .NET classes, it would simplify development (no builds, better intellisense) and maintainability of the code base if Polaris was implemented in pure Powershell

enhancement 
opened Nov 19, 2017 by chriskuech 34
Closed

WIP: Replacing PowerShell Runspaces with Register-EventObject for Asynchronous handling

I coded up something that looks to be working to get some early feedback from you on my first stab at this. I think this makes things soooo much simpler and the debugging experience is grand.

I'll start working on the tests for this so we can try and have all the tests passing again before the PR is accepted.

Issue #93

opened Apr 7, 2018 by Tiberriver256 27
Closed

Investigate the use of Kestrel instead of HttpListener

Kestrel is an awesome webserver from the ASP.NET folks. It might be worth using Kestrel instead of rolling our own webserver using HttpListener.

It has a lot of features that Polaris should have under the hood.

enhancement 
opened Oct 10, 2017 by TylerLeonhardt 24
Closed

WIP: Pure PowerShell Implementation

I wanted to offer pulling this into the repo. I might have time to finish it up this weekend but really I think it's so close someone could accept this PR and finish it up pretty quick.

My goal was to do a straight port over to PowerShell without introducing any breaking changes. I wanted to do it by keeping all of the Pester tests the same and just coding PowerShell until I was finished. I broke my rule though and added a static file server and file browser which meant a modification of one of tests.

I'll see if I can run a Pester test tonight and get added to the comments exactly what tests are failing as work items left to be done.

Reference Enhancement Issue #81 for conversation.

opened Mar 30, 2018 by Tiberriver256 19
Closed

RFC 001: Path Matching/Resolution Strategy

The original implementation of Polaris was that the path requested by the client had to equal the path declared by the New-PolarisRoute function.

The current implementation takes a matching approach. If the path declared by New-PolarisRoute matches the beginning of the requested path the ScriptBlock will execute.

The current implementation of a more flexible path matching strategy allows for scenarios like the built-in file browser where the remainder of the URL can be assumed to be a relative path to the local file but it can be argued that it is too flexible as URLs that are technically "wrong" will match and the ScriptBlock may execute, as mentioned in #116.

We would like to ask for input from the community on a proposed solution currently in Pull Request #119. The proposal is to match the path strategy of Express.js.

This means we would support RegularExpressions for paths and named parameters within the path:

Example paths:

  1. /hello - Would get converted to the following regular expression: ^/hello$. This would guarantee hello would be the only match and return to the original implementation.
  2. /hello.* - Would get converted to the following regular expression: ^/hello.*$. This would match the current implementation and allow for any all requests that begin with hello to trigger the desired scriptlbock
  3. /hello/:firstname/:lastname - Would get converted to the following regular expression: ^/hello/(?<firstname>.*)/(?<lastname>.*). The $Matches from the regular expression would then be converted to a PSCustomObject and be made available within the ScriptBlock as something like $Request.Parameters

As this is a breaking change we would love feedback and additional suggestions on the implementation. Thanks @TimCurwick for the feedback on the PR to bring this out for a more open discussion.

*EDIT: This would introduce the following breaking change. The below request URL would match in the current implementation and would no longer match in the new implementation.

Route path: /flights
Request URL: http://localhost:3000/flights/myspecialflight
RFC 
opened May 7, 2018 by Tiberriver256 18
Closed

New Feature: Path based parameters

*Note this should also fix the matching issue described at the bottom of issue #116

This allows for the following scenario:

New-PolarisGetRoute -Path "/Hello/{Name}" -ScriptBlock {
                $Response.Send("Hello $($Parameters.Name)")
            }

$Result = Invoke-WebRequest -Uri "http://localhost:$Port/hello/Testing" -UseBasicParsing
$Result.Content | Should Be 'Hello Testing'

It introduces a new $Parameters PSCustomObject representing any path based parameters and it also makes route matching more strict as it is now converts paths to a regular expression using Convert-PathParameters function.

At the time a request is made the above mentioned path /Hello/{Name} would get converted to a regular expression of ^/Hello/(?<Name>.*)$ for matching against the client's requested route.

A more basic example would be that /Hello would be converted to ^/Hello$ to guarantee an exact path match. I've also added some test cases to ensure we are throwing 404 errors for paths that don't match exactly.

opened May 5, 2018 by Tiberriver256 17
Open

Polaris support latest powershell version, like powershell 7.1

Hi,

May I ask whether Polaris support the latest powershell version 7.1?

Thanks Eric Xin

opened May 27, 2021 by ericxin1982 2
Open

Possible Memory leak

Polaris Bug Report

Description of the bug

We have Polaris running in a windows container and over time it is consuming more memory.

A clear and concise description of what the bug is.

Steps to reproduce

Steps to reproduce the behavior: Start Polaris as a windows container and monitor memory. At this point we aren't actively using the REST API.

Expected behavior

Start container and the amount of memory to start the process should be used and stay at a consistent amount.

Additional context

Dockerfile we are using FROM mcr.microsoft.com/powershell:lts-nanoserver-1809

USER ContainerAdministrator

RUN setx /M PATH "%PATH%;C:\Program Files\PowerShell"

SHELL ["pwsh", "-Command"]

COPY artifacts C:

RUN ["pwsh.exe", "C:\bootstrap.ps1"]

Expose 8080

cmd C:\Invoke-Polaris.ps1

Entrypoint Script Import-Module Polaris New-PolarisGetRoute -Path "/test" -Scriptblock { $Response.Send('DEVOPSAPI is running'); }

New-PolarisGetRoute -Path "/customers" -Scriptblock { $getCust = "C:\scripts\get-customers.ps1" | Invoke-Expression $Response.Json($getCust); }

New-PolarisGetRoute -Path "/customers/:cid/workflows" -Scriptblock { $cid = $Request.Parameters.cid $getWFs = "C:\scripts\get-workflows.ps1 -CID $cid" | Invoke-Expression $Response.Json($getWFs); }

New-PolarisGetRoute -Path "/customers/:cid/workflows/:wfkey/steps" -Scriptblock { $cid = $Request.Parameters.cid $wfkey = $Request.Parameters.wfkey $getSteps = "C:\scripts\get-workflow-steps.ps1 -CID $cid -WFKEY $wfkey" | Invoke-Expression $Response.Json($getSteps); }

$app = Start-Polaris

while($app.Listener.IsListening) { Wait-Event callbackcomplete }

Version Information

Run the following script and copy and paste the results here:

$Version = [pscustomobject]$PSVersionTable
$Version.PSCompatibleVersions = ($Version.PSCompatibleVersions | foreach { "$($_.Major).$($_.Minor).$($_.Build).$($_.Revision)" }) -join ",  "
(Get-Module Polaris | select Name,Version | ConvertTo-Html -Fragment | Out-String) + ($Version | ConvertTo-Html -Fragment | Out-String)
opened May 4, 2021 by dwinshipIdentifi 1
Open

Minimum requirements for Polaris?

Hello, I would like to develop a script that would run on over 1500 machines. The thing is that the environment differs on the machines. For ex.: 70% - Windows 10 20% - Windows 7 10% - Windows XP

Would like to know what is the minimum version of

  • Powershell
  • .NET Framework
  • other requirements? Thanks.
opened Jan 28, 2021 by this-is-mihai 1
Open

Add support for web socket endpoints

Polaris Feature Request

Is your feature request related to a problem? Please describe

Nope

Describe the solution you'd like

Add support for websockets in Polaris.

New-PolarisWebsocket -Path /my/endpoint -ScriptBlock { }

Describe alternatives you've considered

Implement a websocket server myself, using a C# library.

Additional context

Add any other context or screenshots about the feature request here.

opened Nov 27, 2020 by pcgeek86 0
Open

Polaris leaves behind a couple of event subscribers

Polaris Bug Report

Description of the bug

After running Stop-Polaris and Clear-Polaris, the Polaris module leaves behind a couple of event subscriptions. These should be cleaned up during Clear-Polaris, I believe.

Steps to reproduce

Steps to reproduce the behavior:

New-PolarisGetRoute -Path / -ScriptBlock { }
Start-Polaris
Stop-Polaris
Clear-Polaris

Now run Get-EventSubscriber, and there are a couple of registrations active.

SubscriptionId   : 2
SourceObject     : System.Management.Automation.PowerShell
EventName        : InvocationStateChanged
SourceIdentifier : fee5b04f-61a9-4ab3-a68a-1ee1bc9f3508
Action           : System.Management.Automation.PSEventJob
HandlerDelegate  :
SupportEvent     : False
ForwardEvent     : False

SubscriptionId   : 3
SourceObject     : CallbackEventBridge
EventName        : callbackcomplete
SourceIdentifier : cc883506-5c5e-48a0-b471-930beca121e1
Action           : System.Management.Automation.PSEventJob
HandlerDelegate  :
SupportEvent     : False
ForwardEvent     : False

Expected behavior

No leftover event subscribers are registered in PowerShell.

Version Information

Run the following script and copy and paste the results here:

PSCompatibleVersionsPlatformPSRemotingProtocolVersionSerializationVersionWSManStackVersionPSEditionPSVersionOSGitCommitId
1.0.-1.-1, 2.0.-1.-1, 3.0.-1.-1, 4.0.-1.-1, 5.0.-1.-1, 5.1.10032.0, 6.0.0.-1, 6.1.0.-1, 6.2.0.-1, 7.0.0.-1, 7.1.0.-1Win32NT2.31.1.0.13.0Core7.1.0Microsoft Windows 10.0.190417.1.0
opened Nov 27, 2020 by pcgeek86 0
Open

Start-Polaris missing hostname parameter

Polaris Bug Report

Description of the bug

Polaris version 0.2.0 downloaded from PSGallery today (3/2/2020) is missing the hostname parameter.

Steps to reproduce

Steps to reproduce the behavior:

  1. Install-Module Polaris
  2. Get-Command Start-Polaris -Syntax
  3. Observe:
PS C:\> gcm start-polaris -syntax

Start-Polaris [[-Port] <int>] [[-MinRunspaces] <int>] [[-MaxRunspaces] <int>] [[-Auth] <string>] [[-Polaris] <Object>] [-UseJsonBodyParserMiddleware] [-Https] [<CommonParameters>]
  1. See absence of hostname parameter

Expected behavior

Start-Polaris should provide the hostname parameter in version 0.2.0 according to current repo contents

Version Information

Run the following script and copy and paste the results here:

NameVersion
polaris0.2.0
PSEditionPSCompatibleVersionsPSRemotingProtocolVersionGitCommitIdSerializationVersionPlatformOSWSManStackVersionPSVersion
Core1.0.-1.-1, 2.0.-1.-1, 3.0.-1.-1, 4.0.-1.-1, 5.0.-1.-1, 5.1.10032.0, 6.2.4.-12.36.2.41.1.0.1Win32NTMicrosoft Windows 10.0.17134 3.06.2.4
opened Mar 2, 2020 by jsonofcourse 2

v0.0.1(Apr 3, 2018)

Created a release for documentation purposes.

Contents

    vector-sec AWS PowerShell Python Lambda, or PSPy for short, is a simple Python 2.7 AWS Lambda function designed to execute the PowerShell binary and marshal input/output to PowerShell.
    Badgerati Pode is a Cross-Platform PowerShell web framework for creating REST APIs, Web Sites, and TCP/SMTP servers
    PowerShell PowerShell for every system!
    jantari This PowerShell module lets you create very simple but clickable menus in the PowerShell console.
    ironmansoftware PowerShell Explorer shows information about the PowerShell environment on your machine.
    orbitalquark Textadept is a fast, minimalist, and remarkably extensible cross-platform text editor for programmers.
    sumeetchhetri Framework for Enterprise Application Development, webrtc signalling server, peerjs webrtc, c++ framework, c++ web framework, c++ application framework, c++ rest framework, c++ soap framework, c++ web sites, c++ web applications, c++ driven web development - c++
    latkin PowerShell client for 1Password
    adamdriscoll PowerShell wrapper around Python for .NET to invoke Python from PowerShell
    nickbeau Repository for the Facebook Group PowerShell Scripting
    nohwnd Script, ScriptBlock and module performance profiler for PowerShell 5, and PowerShell 7.
    Cn33liz CScriptShell, a Powershell Host running within cscript.exe
    Mr-Un1k0d3r Run PowerShell command without invoking powershell.exe
    natemrice This is a PowerShell function to render pictures to the PowerShell command line.
    EvotecIT PowerShell Generated Status Page
    bayurstarcool BayurGo is a minimalist web framework written in Go (Golang).
    cosmicjs A cross-platform blog for iOS, Android and web. Content powered by Cosmic JS.
    madrobby Zepto.js is a minimalist JavaScript library for modern browsers, with a jQuery-compatible API
    jroimartin Minimalist Go package aimed at creating Console User Interfaces.
    WebReflection A cross platform, cross WebView, solution to fit 100% any Web page.
    shaarli The personal, minimalist, super-fast, database free, bookmarking service - community repo
    Share this repo

    Related Repos


    Web Frameworks
    2.7k
    A better way to create web api endpoints for ASP.Net 6 that encourages CQRS and Vertical S...
    FastEndpoints A better way to create web api endpoints for ASP.Net 6 that encourages CQRS and Vertical Slice Architecture.
     
    Web Frameworks
    2.5k
    A project for supporting API Endpoints in ASP.NET Core web applications.
    ardalis A project for supporting API Endpoints in ASP.NET Core web applications.
     
    Web Frameworks
    43
    Open Source / i18n / Cross Platform Contact Tracing App by exposure notification framework...
    Covid-19Radar Open Source / i18n / Cross Platform Contact Tracing App by exposure notification framework.
     
    Web Frameworks
    611
    Pode is a Cross-Platform PowerShell web framework for creating REST APIs, Web Sites, and T...
    Badgerati Pode Pode is a Cross-Platform framework, completely written in PowerShell, for creating web servers to host REST APIs, Web Pages, and SMTP/TCP Servers. Pode also allows you to render dynamic files using .pode files,
     
    Web Frameworks
    1.3k
    Modular Application Framework for Blazor
    oqtane Oqtane Framework Oqtane is a Modular Application Framework for Blazor Oqtane uses Blazor, a new web framework for .NET Core that lets you build interactive web UIs using C# instead of JavaScript. Blazor apps are composed of re
     
    Web Frameworks
    1.3k
    Modular Application Framework for Blazor
    oqtane Oqtane Framework Oqtane is a Modular Application Framework for Blazor Oqtane uses Blazor, a new web framework for .NET Core that lets you build interactive web UIs using C# instead of JavaScript. Blazor apps are composed of re
     
    Web Frameworks
    3.1k
    Blazor workshop
    dotnet-presentations Blazor - app building workshop Welcome to the Blazor app building workshop! Blazor is a single-page app framework for building client-side web apps using .NET and WebAssembly. In this workshop we will build a complete Blazor app
     
    Web Frameworks
    488
    A cross-platform, minimalist web framework for PowerShell
    PowerShell Polaris A cross-platform, minimalist web framework for PowerShell. Disclaimer Polaris is currently an unsupported, experimental, proof-of-concept. There is no current plan to turn it into a supported Microsoft pro
     
    Web Frameworks
    1.5k
    Microdot: An open source .NET microservices framework
    gigya Microdot Framework An open source .NET microservices framework Microdot is an open source .NET framework that answers a lot of the needs for easily creating microservices. Some of its main features: Service contai
     
    Popular
    Web Frameworks
    10.9k
    ASP.NET Boilerplate - Web Application Framework
    aspnetboilerplate ASP.NET Boilerplate AppVeyor: What is ABP? ASP.NET Boilerplate is a general purpose application framework especially designed for new modern web applications. It uses already familiar tools and implements best practi
     
    Web Frameworks
    481
    A flexible web framework supports .Net Framework and .Net Core
    zkweb-framework ZKWeb ZKWeb is a flexible web framework for .NET Framework and .NET Core. Why created this framework? I want a better plugin system, one folder one plugin just like django I want an independent mvc framework, because