Is it possible to serve HTML pages with ServiceStack?
I'm evaluating ServiceStack for use in a Windows Service to host REST services. So far, it's excellent and way outperforms WCF. Not to mention its much easier to use.
The Windows Services mentioned above need to be able to provide a simple HTML page to serve as a "dashboard". ServiceStack would of course be used to provide json data for the dashboard, but what about serving the dashboard page, along with images and js? Would this be possible? I would rather not host full-blown ASP.Net and have a strict limitation that IIS will never run on these servers. Scalability shouldnt be a requirement either, since only a single admin machine would ever be displaying the dashboard.
Answer
Using only ServiceStack for web and web services
ServiceStack's new Razor View Engine support
A significant improvement to ServiceStack's HTML story was added in v3.9.11 in the ServiceStack.Razor NuGet package. With this support ServiceStack now graduates to a full Website and Web Services framework that offers a much simpler replacement to WCF, MVC and WebApi.
Full documentation explaining ServiceStack's new HTML story with Razor Support is maintained in the Razor Rockstars demo website:
- http://razor.servicestack.net - ASP.NET Host developed on Win hosted on Linux
- http://razor-console.servicestack.net - Stand-alone Self Host developed on Win hosted on Linux
Full Documentation explaining Razor support and describing its Features is explained in the links above.
Just a REST Service framework with HTML Format
The HTML Content-Type has been added to ServiceStack just as you would expect from a true REST Service framework, i.e. you can simply add Razor Views to enhance your existing services which will only get used when the client requests for the text/html Content-Type (with no effect on the existing registered formats). E.g. this /rockstars REST service can still be accessed in all the other Content-Types:
In addition if your services has the [ClientCanSwapTemplates] attribute, the client can swap the Views and Templates of pages at runtime, e.g. here's the same above page with:
- A Single Page AngularJS App with Client-side rendering
- A different SimpleLayout template
- AngularJS with SimpleLayout template
ServiceStack's natural adoption of the HTML format in this way, makes it trivial to develop 1 set of services that can serve both HTML and rich native mobile and desktop clients.
Other ways to serve HTML
Before Razor support was added there are a couple of strategies of serving HTML pages with ServiceStack:
Use a static html page with ajax calls
If you make a web request for an existing file, it gets returned with the Static File Handler. You can then simply make ajax json calls back to your web services to dynamically generate a page.
The TODO Backbone application in the Windows Service AppHost Starter Template works this way. (as well as most other example projects in ServiceStack :-)
Return a string
Any string returned from your web services gets directly written to the response stream 'as-is', so you can simply return html using your own html templating solution.
Here's a list of other possible return types in ServiceStack and how they're treated.
Using Markdown Razor
The view-engine built into ServiceStack is Markdown Razor - Which was inspired by MVC's Razor but using Markdown syntax. It's quite extensible supporting custom base class and extension methods/utils.
A nice feature of using Markdown Razor is your same web service that returns json,xml, etc can also be a view model for a dynamically generated html page at the same url.
An example of this is the category web service which you can see the results of here: http://www.servicestack.net/docs/category/Framework
and the same service again in JSON, XML, etc. You can also retrieve the partially generated html page (without the template) as well the dynamically generated markdown.
The page was created using the web services DTO/view model which was sent to this MarkdownRazor View https://raw.github.com/ServiceStack/ServiceStack.Examples/master/src/Docs/Views/Category.md
If you have specified a Markdown Razor page for your web service, it is used over the default HTML5 JSON Report that you see now.
The resolution order ServiceStack's uses to resolve the appropriate Markdown template to use for rendering HTML output is:
- If the Web Service specifies a template (via a customized IHttpResult.TemplateName response) - then a View with that name.
- A view with the same name as the Response DTO, looking first in /Views then in /Views/Shared
- A view with the same name as the Request DTO, looking first in /Views then in /Views/Shared
Host ServiceStack at a /custompath
ServiceStack can be used together with or without an existing ASP.NET web application. If your application is HTML-heavy and REST-Services-light a common approach is to host ServiceStack at a /custompath (e.g. /api) so you can use ASP.NET for all HTML page generation.
If using ASP.NET MVC instead, you need to ignore the route in MVC's Global.asax RegisterRoutes():
routes.IgnoreRoute ("servicestack/{*pathInfo}");